PayPal MCP Server

官方

PayPal Model Context Protocol 伺服器可讓您透過函式呼叫與 PayPal API 整合。此協定支援多種工具，以便與不同的 PayPal 服務互動。

文件

PayPal Agent Toolkit

PayPal Agent Toolkit 讓主流的代理框架，包括 OpenAI 的 Agent SDK、LangChain、Vercel 的 AI SDK 以及 Model Context Protocol (MCP)，能夠透過函式呼叫與 PayPal API 整合。它支援 TypeScript，並建立在 PayPal API 和 PayPal SDK 之上。

可用工具

PayPal Agent 工具包提供以下工具：

發票

create_invoice：在 PayPal 系統中建立新發票
list_invoices：列出發票，可選擇分頁和篩選
get_invoice：擷取特定發票的詳細資料
send_invoice：將發票傳送給收件人
send_invoice_reminder：針對現有發票傳送提醒
cancel_sent_invoice：取消已傳送的發票
generate_invoice_qr_code：為發票產生 QR 碼

付款

create_order：根據提供的詳細資料在 PayPal 系統中建立訂單
get_order：擷取訂單的詳細資料
pay_order：處理已授權訂單的付款
create_refund：處理已捕獲付款的退款。
get_refund：取得特定退款的詳細資料。

爭議管理

list_disputes：擷取所有未解決爭議的摘要
get_dispute：擷取特定爭議的詳細資訊
accept_dispute_claim：接受爭議索賠

貨件追蹤

create_shipment_tracking：建立貨件追蹤記錄
get_shipment_tracking：擷取貨件追蹤資訊
update_shipment_tracking：更新貨件追蹤資訊

目錄管理

create_product：在 PayPal 目錄中建立新產品
list_products：列出產品，可選擇分頁和篩選
show_product_details：擷取特定產品的詳細資料

訂閱管理

create_subscription_plan：建立新的訂閱方案
list_subscription_plans：列出訂閱方案
show_subscription_plan_details：擷取特定訂閱方案的詳細資料
create_subscription：建立新的訂閱
show_subscription_details：擷取特定訂閱的詳細資料
update_subscription：更新現有訂閱
cancel_subscription：取消使用中的訂閱

報表與洞察

list_transactions：列出交易，可選擇分頁和篩選
get_merchant_insights：擷取商家的商業智慧指標和分析資料

TypeScript

安裝

除非您想修改此套件，否則不需要此原始碼。如果您只想使用此套件，請執行：

npm install @paypal/agent-toolkit

需求

Node 18+

用法

此程式庫需要設定您帳戶的 client id 和 secret，這些可在您的 PayPal Developer Dashboard 中取得。

此工具包可與 Vercel 的 AI SDK 搭配使用，並可作為工具列表傳遞。如需更多詳細資料，請參閱我們的範例

import { PayPalAgentToolkit } from '@paypal/agent-toolkit/ai-sdk';
const paypalToolkit = new PayPalAgentToolkit({
  clientId: process.env.PAYPAL_CLIENT_ID,
  clientSecret: process.env.PAYPAL_CLIENT_SECRET,
  configuration: {
    actions: {
      invoices: {
        create: true,
        list: true,
        send: true,
        sendReminder: true,
        cancel: true,
        generateQRC: true,
      },
      products: { create: true, list: true, update: true },
      subscriptionPlans: { create: true, list: true, show: true },
      shipment: { create: true, show: true, cancel: true },
      orders: { create: true, get: true },
      disputes: { list: true, get: true },
    },
  },
});

若要使用沙箱模式，請在您的設定中加入 context。

configuration: {
  context: {
    sandbox: true,
  }
}

初始化工作流程

import { PayPalWorkflows, ALL_TOOLS_ENABLED } from '@paypal/agent-toolkit/ai-sdk';
const paypalWorkflows = new PayPalWorkflows({
  clientId: process.env.PAYPAL_CLIENT_ID,
  clientSecret: process.env.PAYPAL_CLIENT_SECRET,
  configuration: {
    actions: ALL_TOOLS_ENABLED,
  },
});

用法

使用工具包

const llm: LanguageModelV1 = getModel(); // The model to be used with ai-sdk
const { text: response } = await generateText({
  model: llm,
  tools: paypalToolkit.getTools(),
  maxSteps: 10,
  prompt: `Create an order for $50 for custom handcrafted item and get the payment link.`,
});

環境變數

可以使用下列環境變數：

PAYPAL_ACCESS_TOKEN：您的 PayPal Access Token
PAYPAL_ENVIRONMENT：設為 SANDBOX 以使用沙箱模式，設為 PRODUCTION 以使用正式環境（預設為 SANDBOX 模式）

本指南說明如何為 PayPal API 整合產生存取權杖，包括如何尋找您的 client ID 和 client secret。

先決條件

PayPal Developer 帳戶（用於沙箱）
PayPal Business 帳戶（用於正式環境）

尋找您的 Client ID 和 Client Secret

建立 PayPal Developer 帳戶：
- 前往 PayPal Developer Dashboard
- 使用您的 PayPal 憑證註冊或登入
存取您的憑證：
- 在 Developer Dashboard 中，點擊選單中的 Apps & Credentials
- 根據您的需求在 Sandbox 和 Live 模式之間切換
建立或檢視應用程式：
- 若要建立新應用程式，請點擊 Create App
- 為您的應用程式命名，並選擇要關聯的 Business 帳戶
- 對於現有應用程式，點擊應用程式名稱以檢視詳細資料
擷取憑證：
- 建立或選取應用程式後，您會看到一個畫面，其中包含您的：
  - Client ID：應用程式的公開識別碼
  - Client Secret：私密金鑰（點擊「顯示」後顯示）
- 請安全地儲存這些憑證，因為它們是產生存取權杖所必需的

產生存取權杖

使用 cURL

curl -v https://api-m.sandbox.paypal.com/v1/oauth2/token \\
  -H \"Accept: application/json\" \\
  -H \"Accept-Language: en_US\" \\
  -u \"CLIENT_ID:CLIENT_SECRET\" \\
  -d \"grant_type=client_credentials\"

將 CLIENT_ID 和 CLIENT_SECRET 替換為您的實際憑證。對於正式環境，請使用 https://api-m.paypal.com 而非沙箱 URL。

使用 Postman

建立一個指向 https://api-m.sandbox.paypal.com/v1/oauth2/token 的新請求
將方法設為 POST
在 Authorization 下，選取 Basic Auth 並輸入您的 Client ID 和 Client Secret
在 Body 下，選取 x-www-form-urlencoded 並新增一個鍵 grant_type，值為 client_credentials
傳送請求

回應

成功的回應看起來會像這樣：

{
  "scope": "...",
  "access_token": "Your Access Token",
  "token_type": "Bearer",
  "app_id": "APP-80W284485P519543T",
  "expires_in": 32400,
  "nonce": "..."
}

複製 access_token 的值，以便在您的 Claude Desktop 整合中使用。

權杖詳細資料

沙箱權杖：有效期為 3-8 小時
正式環境權杖：有效期為 8 小時
建議在權杖到期前實作權杖刷新邏輯

搭配 Claude Desktop 使用權杖

取得存取權杖後，請更新 Claude Desktop 連接器設定中的 PAYPAL_ACCESS_TOKEN 值：

{
  "env": {
    "PAYPAL_ACCESS_TOKEN": "YOUR_NEW_ACCESS_TOKEN",
    "PAYPAL_ENVIRONMENT": "SANDBOX"
  }
}

最佳實務

安全地儲存 client ID 和 client secret
實作權杖刷新邏輯以處理權杖到期
使用特定環境的權杖（沙箱用於測試，正式環境用於真實交易）
避免在應用程式碼中硬編碼權杖

免責聲明

AI 生成的內容可能不準確或不完整。使用者有責任在依賴任何資訊之前獨立驗證。PayPal 對輸出準確性不做任何保證，且不對因其使用而產生的任何決策、行動或後果負責。