# MCP AI 整合 (/guides/mcp)





MCP AI 整合 [#mcp-ai-整合]

**MCP (Model Context Protocol)** 是一個讓 AI 助手可以直接操作外部 API 的協議。透過 Recur MCP Server，AI 可以自動幫你：

* 建立 API Key 和訂閱方案
* 產生符合你專案的整合程式碼
* 檢查整合狀態並提供建議
* 回答關於 Recur API 的問題

支援的平台 [#支援的平台]

<Tabs items="['Cursor', 'Claude Code', 'Claude Desktop', 'Antigravity', 'Replit', 'Lovable', 'Bolt.new']">
  <Tab value="Cursor">
    Cursor [#cursor]

    點擊以下按鈕一鍵安裝：

    <a href="cursor://anysphere.cursor-deeplink/mcp/install?name=recur&config=eyJ1cmwiOiJodHRwczovL21jcC5yZWN1ci50dy9tY3AifQ%3D%3D" target="_blank" rel="noopener noreferrer" title="一鍵安裝 Recur MCP 到 Cursor">
      <picture>
        <source srcSet="https://cursor.com/deeplink/mcp-install-light.svg" media="(prefers-color-scheme: light)" />

        <img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Install MCP Server" className="h-10 w-auto" />
      </picture>
    </a>

    或手動編輯 Cursor MCP 設定檔 (`~/.cursor/mcp.json`)：

    ```json
    {
      "mcpServers": {
        "recur": {
          "url": "https://mcp.recur.tw/"
        }
      }
    }
    ```

    <Callout type="info">
      Cursor 會自動偵測設定變更。如果沒有立即生效，請重新啟動 Cursor。
    </Callout>

    驗證安裝 [#驗證安裝]

    在 Cursor 中開啟 Settings → MCP，確認 `recur` 伺服器已連線。
  </Tab>

  <Tab value="Claude Code">
    Claude Code (CLI) [#claude-code-cli]

    在終端機中執行以下指令：

    ```bash
    claude mcp add --transport http recur https://mcp.recur.tw/
    ```

    <Callout type="info">
      首次使用時，Claude Code 會自動開啟瀏覽器請求授權。授權完成後即可開始使用。
    </Callout>

    驗證安裝 [#驗證安裝-1]

    執行以下指令確認 MCP Server 已正確安裝：

    ```bash
    claude mcp list
    ```

    你應該會看到 `recur` 在列表中。
  </Tab>

  <Tab value="Claude Desktop">
    Claude Desktop [#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-20256]

    較新版本的 Claude Desktop 原生支援 HTTP transport：

    ```json
    {
      "mcpServers": {
        "recur": {
          "url": "https://mcp.recur.tw/"
        }
      }
    }
    ```

    方法二：mcp-remote Bridge（舊版 Claude Desktop） [#方法二mcp-remote-bridge舊版-claude-desktop]

    如果方法一不生效，改用 `mcp-remote` 做 stdio ↔ HTTP 橋接：

    <Callout type="warn">
      需要 **Node.js 20 以上**。Node 18 會因缺少 `File` API 導致啟動失敗。
    </Callout>

    ```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/` 確認伺服器可達
  </Tab>

  <Tab value="Antigravity">
    Antigravity [#antigravity]

    [Antigravity](https://anyhive.com/antigravity) 是一個 AI 程式設計平台。編輯 MCP 設定檔，新增 Recur MCP Server：

    ```json
    {
      "mcpServers": {
        "recur": {
          "command": "npx",
          "args": [
            "-y",
            "mcp-remote",
            "https://mcp.recur.tw/"
          ]
        }
      }
    }
    ```

    <Callout type="info">
      首次使用時會自動開啟瀏覽器請求授權。授權完成後即可開始使用。
    </Callout>
  </Tab>

  <Tab value="Replit">
    Replit [#replit]

    點擊以下按鈕一鍵安裝：

    <a href="https://replit.com/integrations?mcp=eyJkaXNwbGF5TmFtZSI6IlJlY3VyIE1DUCIsImJhc2VVcmwiOiJodHRwczovL21jcC5yZWN1ci50dy9tY3AifQ==" target="_blank" rel="noopener noreferrer" title="一鍵安裝 Recur MCP 到 Replit">
      <img src="https://replit.com/badge?caption=Add%20to%20Replit" alt="Add to Replit" className="h-10 w-auto" />
    </a>

    或在 Replit 專案中，點擊 **Tools** → **MCP Servers** → 輸入：

    ```
    https://mcp.recur.tw/
    ```
  </Tab>

  <Tab value="Lovable">
    Lovable [#lovable]

    在 Lovable 專案設定中新增 MCP Server URL：

    ```
    https://mcp.recur.tw/
    ```

    詳細步驟請參考 [Lovable MCP 文件](https://docs.lovable.dev/features/mcp-support)。
  </Tab>

  <Tab value="Bolt.new">
    Bolt.new [#boltnew]

    在 Bolt.new 專案設定中新增 MCP Server URL：

    ```
    https://mcp.recur.tw/
    ```
  </Tab>
</Tabs>

首次授權 [#首次授權]

首次使用 MCP 時，系統會引導你登入 Recur 帳號並授權 AI 存取你的組織資料：

<Steps>
  <Step>
    發起授權 [#發起授權]

    當 AI 嘗試使用 Recur 工具時，會自動開啟授權頁面。
  </Step>

  <Step>
    登入 Recur [#登入-recur]

    如果尚未登入，請先登入你的 Recur 帳號。
  </Step>

  <Step>
    授權存取 [#授權存取]

    確認授權範圍後，點擊「授權」按鈕。
  </Step>

  <Step>
    開始使用 [#開始使用]

    授權完成後，AI 就可以開始幫你管理 Recur 設定了！
  </Step>
</Steps>

授權範圍 [#授權範圍]

當你授權 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` | 為你的組織建立、更新、封存產品                        |

<Callout type="info">
  **權限說明**：AI 助手只能執行你明確授權的操作。例如，如果只授權 `products:read` 而沒有 `products:write`，AI 可以查看你的產品但無法建立新產品。
</Callout>

權限與工具對應 [#權限與工具對應]

每個 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 活動監控 [#api-活動監控]

| 工具名稱                       | 說明               |
| -------------------------- | ---------------- |
| `get_recent_api_calls`     | 取得最近的 API 呼叫紀錄   |
| `get_api_activity_summary` | 取得 API 活動摘要和整合進度 |
| `get_failed_api_calls`     | 取得失敗的 API 呼叫用於診斷 |

使用範例 [#使用範例]

安裝 MCP 後，試試這些提示：

快速開始 [#快速開始]

```
幫我整合 Recur 訂閱付款到我的 React 專案
```

建立 API Key [#建立-api-key]

```
幫我建立一個 sandbox publishable key
```

建立訂閱方案 [#建立訂閱方案]

```
建立一個月費 NT$299 的 Pro 方案，包含 14 天免費試用
```

取得整合程式碼 [#取得整合程式碼]

```
給我 Next.js 的整合程式碼範例
```

檢查整合狀態 [#檢查整合狀態]

```
檢查我的 Recur 整合狀態
```

查看營收數據 [#查看營收數據]

```
這個月的 MRR 是多少？跟上個月比成長了多少？
```

查看訂閱概況 [#查看訂閱概況]

```
列出所有活躍訂閱，顯示即將續約的訂閱
```

查看顧客詳情 [#查看顧客詳情]

```
查詢 test@example.com 這位顧客的訂閱歷史和 LTV
```

分析流失率 [#分析流失率]

```
本月的流失率是多少？哪些訂閱已經取消？
```

安全性 [#安全性]

<Callout type="warn">
  MCP 使用 OAuth 2.0 授權機制，AI 只能存取你明確授權的組織資料。你可以隨時在 Recur 儀表板中撤銷授權。
</Callout>

安全機制 [#安全機制]

* **OAuth 2.0 授權**：使用業界標準的授權協議
* **Token 自動刷新**：Access Token 過期後會自動刷新，無需重新授權
* **範圍限制**：AI 只能執行你明確授權的操作
* **稽核記錄**：所有 API 操作都會記錄在活動日誌中

AI 無法存取的資料 [#ai-無法存取的資料]

為了保護你和你客戶的隱私，MCP **不會**提供以下資料的存取權限：

| 無法存取的資料       | 說明                                                                    |
| ------------- | --------------------------------------------------------------------- |
| 完整信用卡卡號       | Recur 採用 Tokenization 機制，系統從未經手完整卡號。金流商僅提供卡號前六碼、末四碼及到期日供識別用途，這是業界標準做法 |
| Secret Key 內容 | 只能建立新金鑰，無法查看現有金鑰的密鑰內容                                                 |
| 帳戶餘額          | 你的 Recur 帳戶收款餘額和提領紀錄                                                  |
| 密碼和認證資訊       | 客戶的登入密碼和驗證碼                                                           |

<Callout type="info">
  MCP 的設計原則是「最小權限」：只提供 AI 完成任務所需的資料存取權限。如果你不需要 AI 存取商業資料，可以在授權時只授予基本整合權限。
</Callout>

常見問題 [#常見問題]

Q: MCP 支援哪些 AI 平台？ [#q-mcp-支援哪些-ai-平台]

目前支援 Cursor、Claude Code、Claude Desktop、Antigravity、Replit、Lovable、Bolt.new。未來會持續新增更多平台支援。

Q: 如何撤銷 MCP 授權？ [#q-如何撤銷-mcp-授權]

登入 [Recur 儀表板](https://app.recur.tw) → 設定 → 已連結的應用程式，找到對應的 MCP 授權並點擊「撤銷」。

Q: MCP 會存取我的付款資料嗎？ [#q-mcp-會存取我的付款資料嗎]

MCP 可以存取訂單、訂閱和營收統計等商業資料（需要授權相應的 scope）。關於信用卡資訊，Recur 採用 Tokenization 機制，系統從未經手完整卡號，僅保存金流商提供的授權碼、卡號前六碼、末四碼及到期日（業界標準做法，用於識別卡片），確保交易安全及消費者權益。

Q: 可以同時在多個平台使用 MCP 嗎？ [#q-可以同時在多個平台使用-mcp-嗎]

可以。每個平台會有獨立的授權，你可以根據需求授權或撤銷。

下一步 [#下一步]

* [SDK 快速開始](/guides/getting-started) - 手動整合 SDK
* [API 參考](/api) - 完整的 API 文件
* [Webhook 整合](/guides/webhooks) - 接收訂閱事件通知