PayPal

npx add-mcp 'https://mcp.paypal.com/mcp'

PayPal Agent 工具包

PayPal Agent 工具包使流行的智能体框架（包括 OpenAI 的 Agent SDK、LangChain、Vercel 的 AI SDK 和 Model Context Protocol (MCP)）能够通过函数调用与 PayPal API 集成。它支持 TypeScript，并基于 PayPal API 和 PayPal SDK 构建。

可用工具

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

发票

• create_invoice：在 PayPal 系统中创建新发票，包括收件人账单详情、行项目、发票备注、自定义颜色主题、可选的运费以及启用 PAY_BY_BANK 作为支付方式的选项

• list_invoices：列出发票，支持可选的分页和筛选

• get_invoice：检索特定发票的详细信息

• send_invoice：向收件人发送发票

• send_invoice_reminder：为现有发票发送提醒

• cancel_sent_invoice：取消已发送的发票

• generate_invoice_qr_code：为发票生成二维码

• delete_invoice：永久删除草稿或计划中的发票

• generate_invoice_number：生成商户可用的下一个发票编号

• search_invoicing：搜索发票或定期发票系列

• update_invoicing：更新现有发票或定期发票系列（全量替换）

• cancel_invoice_auto_reminder：取消发票的所有计划自动提醒

• record_payment_for_invoice：记录针对发票的外部或手动付款

• record_refund_for_invoice：记录针对发票的退款

• create_conditional_rules_for_invoice：为发票创建条件规则，例如提前付款折扣或自动取消日期

• create_recurring_series：创建定期发票系列，按计划自动生成并发送发票

• activate_recurring_series：激活草稿状态的定期发票系列

• get_recurring_series：检索特定定期发票系列的详细信息

• cancel_recurring_series：取消处于活动状态的定期发票系列

• delete_recurring_series：删除草稿状态的定期发票系列

支付

• 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+

使用方法

该库需要使用您账户的客户端 ID 和密钥进行配置，这些信息可在 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,
        createRecurringSeries: true,
        list: true,
        send: true,
        sendReminder: true,
        cancel: true,
        delete: true,
        generateQRC: true,
        generateInvoiceNumber: true,
        search: true,
        update: true,
        cancelReminders: true,
        recordPayment: true,
        recordRefund: true,
        createConditionalRules: 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 },
    },
  },
});

要使用沙盒模式，请在配置中添加相关上下文。

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 访问令牌
• PAYPAL_ENVIRONMENT：设置为 SANDBOX 以使用沙盒模式，设置为 PRODUCTION 以使用生产模式（默认为 SANDBOX 模式）

本指南介绍如何为 PayPal API 集成生成访问令牌，包括如何查找您的客户端 ID 和客户端密钥。

前提条件

• PayPal 开发者账户（用于沙盒）
• PayPal 商业账户（用于生产）

查找您的客户端 ID 和客户端密钥

1. 创建 PayPal 开发者账户：

   • 前往 PayPal Developer Dashboard
   • 使用您的 PayPal 凭据注册或登录

2. 访问您的凭据：

   • 在开发者仪表板中，点击菜单中的 Apps & Credentials
   • 根据您的需求在 Sandbox 和 Live 模式之间切换

3. 创建或查看应用：

   • 要创建新应用，请点击 Create App
   • 为您的应用命名，并选择要关联的商业账户
   • 对于现有应用，点击应用名称以查看详细信息

4. 获取凭据：

   • 创建或选择应用后，您将看到一个包含以下信息的屏幕：
     • Client ID：您应用的公共标识符
     • Client Secret：私密密钥（点击 "Show" 后显示）
   • 请安全保存这些凭据，因为生成访问令牌时需要用到它们

生成访问令牌

使用 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

1. 创建新请求，目标为 https://api-m.sandbox.paypal.com/v1/oauth2/token
2. 将方法设置为 POST
3. 在 Authorization 下，选择 Basic Auth 并输入您的客户端 ID 和客户端密钥
4. 在 Body 下，选择 x-www-form-urlencoded 并添加键 grant_type，值为 client_credentials
5. 发送请求

响应

成功的响应将如下所示：

{
  "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"
  }
}

最佳实践

1. 安全存储客户端 ID 和客户端密钥
2. 实现令牌刷新逻辑以处理令牌过期
3. 使用特定环境的令牌（沙盒用于测试，生产用于真实交易）
4. 避免在应用程序代码中硬编码令牌

免责声明

AI 生成的内容可能不准确或不完整。用户有责任在依赖任何信息之前独立核实其准确性。PayPal 不对输出准确性作任何保证，也不对因使用输出而产生的任何决策、行动或后果承担责任。