--- title: MCP AI 整合 description: 使用 MCP (Model Context Protocol) 讓 AI 助手自動整合 Recur 付款功能 --- # MCP AI 整合 **MCP (Model Context Protocol)** 是一個讓 AI 助手可以直接操作外部 API 的協議。透過 Recur MCP Server，AI 可以自動幫你： - 建立 API Key 和訂閱方案 - 產生符合你專案的整合程式碼 - 檢查整合狀態並提供建議 - 回答關於 Recur API 的問題 ## 支援的平台 ### Cursor 點擊以下按鈕一鍵安裝： Install MCP Server 或手動編輯 Cursor MCP 設定檔 (`~/.cursor/mcp.json`)： ```json { "mcpServers": { "recur": { "url": "https://mcp.recur.tw/" } } } ``` Cursor 會自動偵測設定變更。如果沒有立即生效，請重新啟動 Cursor。 #### 驗證安裝 在 Cursor 中開啟 Settings → MCP，確認 `recur` 伺服器已連線。 ### Claude Code (CLI) 在終端機中執行以下指令： ```bash claude mcp add --transport http recur https://mcp.recur.tw/ ``` 首次使用時，Claude Code 會自動開啟瀏覽器請求授權。授權完成後即可開始使用。 #### 驗證安裝 執行以下指令確認 MCP Server 已正確安裝： ```bash claude mcp list ``` 你應該會看到 `recur` 在列表中。 ### Claude Desktop 編輯 Claude Desktop 設定檔，新增 Recur MCP Server： **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` #### 方法一：直接連線（推薦，需 Claude Desktop 2025.6+） 較新版本的 Claude Desktop 原生支援 HTTP transport： ```json { "mcpServers": { "recur": { "url": "https://mcp.recur.tw/" } } } ``` #### 方法二：mcp-remote Bridge（舊版 Claude Desktop） 如果方法一不生效，改用 `mcp-remote` 做 stdio ↔ HTTP 橋接： 需要 **Node.js 20 以上**。Node 18 會因缺少 `File` API 導致啟動失敗。 ```json { "mcpServers": { "recur": { "command": "npx", "args": ["-y", "mcp-remote", "https://mcp.recur.tw/"] } } } ``` 如果系統預設 Node 版本低於 20，請指定完整路徑： ```json { "mcpServers": { "recur": { "command": "/Users/YOUR_USERNAME/.nvm/versions/node/v22.12.0/bin/npx", "args": ["-y", "mcp-remote", "https://mcp.recur.tw/"] } } } ``` 重新啟動 Claude Desktop 後即可使用。首次連線會開啟瀏覽器進行 OAuth 授權。 #### 疑難排解 **找不到 MCP Server / 連線失敗：** 1. 確認 JSON 語法正確（可用 `cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | python3 -m json.tool` 驗證） 2. 完全關閉並重新開啟 Claude Desktop（不只是關閉視窗） 3. 開啟 Claude Desktop 的 MCP 日誌：**Help → Show MCP Log**（macOS）查看詳細錯誤 **`File is not defined` 或 `ReferenceError` 錯誤：** - Node.js 版本太舊。`mcp-remote` 需要 Node.js 20+ - 執行 `node --version` 確認版本，若低於 20 請升級或指定較新版本的完整路徑 **`npm error 404 Not Found` 錯誤：** - 套件名稱是 `mcp-remote`（不是 `@anthropic-ai/mcp-remote`） **OAuth 授權頁面沒有開啟：** - 確認防火牆沒有擋住 `https://mcp.recur.tw/` - 嘗試手動在瀏覽器開啟 `https://mcp.recur.tw/` 確認伺服器可達 ### Antigravity [Antigravity](https://anyhive.com/antigravity) 是一個 AI 程式設計平台。編輯 MCP 設定檔，新增 Recur MCP Server： ```json { "mcpServers": { "recur": { "command": "npx", "args": [ "-y", "mcp-remote", "https://mcp.recur.tw/" ] } } } ``` 首次使用時會自動開啟瀏覽器請求授權。授權完成後即可開始使用。 ### Replit 點擊以下按鈕一鍵安裝： Add to Replit 或在 Replit 專案中，點擊 **Tools** → **MCP Servers** → 輸入： ``` https://mcp.recur.tw/ ``` ### Lovable 在 Lovable 專案設定中新增 MCP Server URL： ``` https://mcp.recur.tw/ ``` 詳細步驟請參考 [Lovable MCP 文件](https://docs.lovable.dev/features/mcp-support)。 ### Bolt.new 在 Bolt.new 專案設定中新增 MCP Server URL： ``` https://mcp.recur.tw/ ``` ## 首次授權 首次使用 MCP 時，系統會引導你登入 Recur 帳號並授權 AI 存取你的組織資料： ### 發起授權 當 AI 嘗試使用 Recur 工具時，會自動開啟授權頁面。 ### 登入 Recur 如果尚未登入，請先登入你的 Recur 帳號。 ### 授權存取 確認授權範圍後，點擊「授權」按鈕。 ### 開始使用 授權完成後，AI 就可以開始幫你管理 Recur 設定了！ ## 授權範圍 當你授權 AI 助手存取 Recur 時，會根據需要授予以下權限。這些權限讓 AI 可以**從你的 Recur 帳號讀取資料或執行操作**（不是 Recur 存取你的 AI 平台資料）。 ### 身份驗證權限 | 權限 | 說明 | |------|------| | `openid` | 驗證你是 Recur 帳號的擁有者 | | `profile` | 讀取你在 Recur 上的顯示名稱 | | `email` | 讀取你的 Recur 帳號 Email 地址 | | `offline_access` | 允許 AI 在你未主動使用時仍可執行已授權的操作 | ### 資料讀取權限 | 權限 | 說明 | |------|------| | `org:read` | 讀取你的組織名稱、設定狀態等基本資訊 | | `api-keys:read` | 列出你組織的 API 金鑰（僅顯示金鑰名稱和類型，不會暴露密鑰內容） | | `products:read` | 列出你建立的所有產品和定價資訊 | | `integration:verify` | 檢查你的 SDK 整合是否正確設定 | ### 商業資料權限 | 權限 | 說明 | |------|------| | `orders:read` | 讀取訂單、付款紀錄（用於營收分析） | | `subscriptions:read` | 讀取顧客訂閱狀態、帳單週期、續約資訊 | | `customers:read` | 讀取顧客名單、聯絡資訊、訂閱紀錄 | | `analytics:read` | 讀取 MRR、ARR、流失率等營收指標 | ### 操作執行權限 | 權限 | 說明 | |------|------| | `api-keys:write` | 為你的組織建立新的 Publishable Key 或 Secret Key | | `products:write` | 為你的組織建立、更新、封存產品 | **權限說明**：AI 助手只能執行你明確授權的操作。例如，如果只授權 `products:read` 而沒有 `products:write`，AI 可以查看你的產品但無法建立新產品。 ### 權限與工具對應 每個 MCP 工具需要特定的權限才能執行： | 工具 | 所需權限 | |------|---------| | `get_organization` | `org:read` | | `list_api_keys` | `api-keys:read` | | `create_api_key` | `api-keys:write` | | `list_products` | `products:read` | | `create_product` | `products:write` | | `update_product` | `products:write` | | `archive_product` | `products:write` | | `get_setup_overview` | `integration:verify` | | `list_orders` | `orders:read` | | `get_order` | `orders:read` | | `list_subscriptions` | `subscriptions:read` | | `get_subscription` | `subscriptions:read` | | `list_customers` | `customers:read` | | `get_customer` | `customers:read` | | `get_revenue_summary` | `analytics:read` | | `get_metrics` | `analytics:read` | ## 可用的工具 MCP Server 提供以下工具供 AI 使用： ### 組織與設定 | 工具名稱 | 說明 | |---------|------| | `get_organization` | 取得組織資訊和設定狀態 | | `list_api_keys` | 列出所有 API 金鑰 | | `create_api_key` | 建立新的 API 金鑰（Sandbox/Production） | | `get_setup_overview` | 取得整合狀態和程式碼範例 | | `run_health_check` | 執行完整的健康檢查 | | `verify_api_key` | 驗證 API 金鑰是否有效 | ### 產品管理 | 工具名稱 | 說明 | |---------|------| | `list_products` | 列出所有訂閱方案和產品 | | `create_product` | 建立新的訂閱方案或產品 | | `update_product` | 更新產品名稱、價格、狀態 | | `archive_product` | 封存產品（軟刪除） | | `validate_product_price` | 驗證價格格式是否正確 | ### 商業資料 | 工具名稱 | 說明 | |---------|------| | `list_orders` | 列出訂單和付款紀錄 | | `get_order` | 取得特定訂單的詳細資訊 | | `list_subscriptions` | 列出訂閱資料 | | `get_subscription` | 取得特定訂閱的詳細資訊 | | `list_customers` | 列出顧客名單 | | `get_customer` | 取得特定顧客的詳細資訊和 LTV | ### 營收分析 | 工具名稱 | 說明 | |---------|------| | `get_revenue_summary` | 取得營收摘要（MRR、ARR、成長率） | | `get_metrics` | 取得業務指標（流失率、轉換率）| ### 開發輔助 | 工具名稱 | 說明 | |---------|------| | `get_quick_start` | 取得快速開始的整合程式碼 | | `troubleshoot` | 根據錯誤訊息診斷問題 | | `get_hook_details` | 取得 React Hooks 的詳細文件 | | `validate_code` | 檢查程式碼是否有常見問題 | | `get_component_template` | 取得 React 元件模板 | | `get_sdk_documentation` | 取得 SDK 模組結構文件 | ### API 活動監控 | 工具名稱 | 說明 | |---------|------| | `get_recent_api_calls` | 取得最近的 API 呼叫紀錄 | | `get_api_activity_summary` | 取得 API 活動摘要和整合進度 | | `get_failed_api_calls` | 取得失敗的 API 呼叫用於診斷 | ## 使用範例 安裝 MCP 後，試試這些提示： ### 快速開始 ``` 幫我整合 Recur 訂閱付款到我的 React 專案 ``` ### 建立 API Key ``` 幫我建立一個 sandbox publishable key ``` ### 建立訂閱方案 ``` 建立一個月費 NT$299 的 Pro 方案，包含 14 天免費試用 ``` ### 取得整合程式碼 ``` 給我 Next.js 的整合程式碼範例 ``` ### 檢查整合狀態 ``` 檢查我的 Recur 整合狀態 ``` ### 查看營收數據 ``` 這個月的 MRR 是多少？跟上個月比成長了多少？ ``` ### 查看訂閱概況 ``` 列出所有活躍訂閱，顯示即將續約的訂閱 ``` ### 查看顧客詳情 ``` 查詢 test@example.com 這位顧客的訂閱歷史和 LTV ``` ### 分析流失率 ``` 本月的流失率是多少？哪些訂閱已經取消？ ``` ## 安全性 MCP 使用 OAuth 2.0 授權機制，AI 只能存取你明確授權的組織資料。你可以隨時在 Recur 儀表板中撤銷授權。 ### 安全機制 - **OAuth 2.0 授權**：使用業界標準的授權協議 - **Token 自動刷新**：Access Token 過期後會自動刷新，無需重新授權 - **範圍限制**：AI 只能執行你明確授權的操作 - **稽核記錄**：所有 API 操作都會記錄在活動日誌中 ### AI 無法存取的資料 為了保護你和你客戶的隱私，MCP **不會**提供以下資料的存取權限： | 無法存取的資料 | 說明 | |---------------|------| | 完整信用卡卡號 | Recur 採用 Tokenization 機制，系統從未經手完整卡號。金流商僅提供卡號前六碼、末四碼及到期日供識別用途，這是業界標準做法 | | Secret Key 內容 | 只能建立新金鑰，無法查看現有金鑰的密鑰內容 | | 帳戶餘額 | 你的 Recur 帳戶收款餘額和提領紀錄 | | 密碼和認證資訊 | 客戶的登入密碼和驗證碼 | MCP 的設計原則是「最小權限」：只提供 AI 完成任務所需的資料存取權限。如果你不需要 AI 存取商業資料，可以在授權時只授予基本整合權限。 ## 常見問題 ### Q: MCP 支援哪些 AI 平台？ 目前支援 Cursor、Claude Code、Claude Desktop、Antigravity、Replit、Lovable、Bolt.new。未來會持續新增更多平台支援。 ### Q: 如何撤銷 MCP 授權？ 登入 [Recur 儀表板](https://app.recur.tw) → 設定 → 已連結的應用程式，找到對應的 MCP 授權並點擊「撤銷」。 ### Q: MCP 會存取我的付款資料嗎？ MCP 可以存取訂單、訂閱和營收統計等商業資料（需要授權相應的 scope）。關於信用卡資訊，Recur 採用 Tokenization 機制，系統從未經手完整卡號，僅保存金流商提供的授權碼、卡號前六碼、末四碼及到期日（業界標準做法，用於識別卡片），確保交易安全及消費者權益。 ### Q: 可以同時在多個平台使用 MCP 嗎？ 可以。每個平台會有獨立的授權，你可以根據需求授權或撤銷。 ## 下一步 - [SDK 快速開始](/getting-started/sdk) - 手動整合 SDK - [API 參考](/api-reference) - 完整的 API 文件 - [Webhook 整合](/guides/webhooks) - 接收訂閱事件通知