PayPal MCP 服务器

这是一个提供与 PayPal API 全面集成的模型上下文协议（MCP）服务器。该服务器通过标准化接口实现与 PayPal 的支付处理、发票开具、订阅管理和业务操作的无缝交互。

功能

支付处理

• 订单管理：创建、更新和跟踪订单
• 支付处理：使用多种方法处理支付
• 支付令牌：为将来使用创建和管理支付令牌
• 争议管理：处理支付争议和解决方案

业务操作

• 产品管理：创建和管理产品目录
• 发票开具：生成并发送专业发票
• 批量付款：向多个收款人处理批量付款
• 订阅管理：创建和管理定期计费

用户管理

• 身份验证：验证用户身份
• 用户信息：检索和管理用户数据
• 网页配置文件管理：自定义结账体验

架构

graph TB
    subgraph "MCP Environment"
        Client[MCP Client]
        Server[PayPal MCP Server]
        Validation[Input Validation]
        Auth[OAuth Authentication]
        Cache[Token Cache]
        ErrorHandler[Error Handler]
    end

    subgraph "PayPal APIs"
        Orders[Orders API]
        Payments[Payments API]
        Payouts[Payouts API]
        Invoicing[Invoicing API]
        Products[Products API]
        Subscriptions[Subscriptions API]
        Disputes[Disputes API]
        Identity[Identity API]
    end

    Client --> |Request| Server
    Server --> |Response| Client
    Server --> Validation
    Server --> Auth
    Auth --> Cache
    Auth --> |Access Token| PayPal
    Server --> ErrorHandler

    Server --> Orders
    Server --> Payments
    Server --> Payouts
    Server --> Invoicing
    Server --> Products
    Server --> Subscriptions
    Server --> Disputes
    Server --> Identity

    style Client fill:#f9f,stroke:#333,stroke-width:2px
    style Server fill:#bbf,stroke:#333,stroke-width:2px
    style Auth fill:#bfb,stroke:#333,stroke-width:2px
    style Validation fill:#bfb,stroke:#333,stroke-width:2px
    style Cache fill:#fbb,stroke:#333,stroke-width:2px
    style ErrorHandler fill:#fbb,stroke:#333,stroke-width:2px

安装

前提条件

• Node.js 16.x 或更高版本
• 拥有 API 凭证的 PayPal 开发者账号

手动安装

1. 克隆仓库

   git clone https://github.com/arbuthnot-eth/PayPal-MCP.git
   cd PayPal-MCP
   

2. 安装依赖

   npm install
   

3. 构建项目

   npm run build
   

4. 在您的 MCP 设置文件中配置 PayPal 凭证：

   {
     "mcpServers": {
       "paypal": {
         "command": "node",
         "args": ["path/to/paypal-mcp/build/index.js"],
         "env": {
           "PAYPAL_CLIENT_ID": "your_client_id",
           "PAYPAL_CLIENT_SECRET": "your_client_secret",
           "PAYPAL_ENVIRONMENT": "sandbox" // 或 "live"
         },
         "disabled": false,
         "autoApprove": []
       }
     }
   }
   

可用工具

支付操作

create_payment_token

为将来使用创建一个支付令牌。

{
  customer: {
    id: string;
    email_address?: string;
  };
  payment_source: {
    card?: {
      name: string;
      number: string;
      expiry: string;
      security_code: string;
    };
    paypal?: {
      email_address: string;
    };
  };
}

create_order

在 PayPal 中创建一个新订单。

{
  intent: 'CAPTURE' | 'AUTHORIZE';
  purchase_units: Array<{
    amount: {
      currency_code: string;
      value: string;
    };
    description?: string;
    reference_id?: string;
    items?: Array<{
      name: string;
      quantity: string;
      unit_amount: {
        currency_code: string;
        value: string;
      };
    }>;
  }>;
  application_context?: {
    brand_name?: string;
    shipping_preference?: 'GET_FROM_FILE' | 'NO_SHIPPING' | 'SET_PROVIDED_ADDRESS';
    user_action?: 'CONTINUE' | 'PAY_NOW';
  };
}

capture_order

对已授权的订单进行支付捕获。

{
  order_id: string;
  payment_source?: {
    token?: {
      id: string;
      type: string;
    };
  };
}

create_subscription

为定期计费创建一个订阅。

{
  plan_id: string;
  subscriber: {
    name: {
      given_name: string;
      surname: string;
    };
    email_address: string;
  };
  application_context?: {
    brand_name?: string;
    shipping_preference?: 'GET_FROM_FILE' | 'NO_SHIPPING' | 'SET_PROVIDED_ADDRESS';
    user_action?: 'CONTINUE' | 'SUBSCRIBE_NOW';
    payment_method?: {
      payer_selected?: string;
      payee_preferred?: string;
    };
  };
}

业务操作

create_product

在目录中创建一个新的产品。

{
  name: string;
  description: string;
  type: 'PHYSICAL' | 'DIGITAL' | 'SERVICE';
  category: string;
  image_url?: string;
  home_url?: string;
}

create_invoice

生成一张新的发票。

{
  invoice_number: string;
  reference: string;
  currency_code: string;
  recipient_email: string;
  items: Array<{
    name: string;
    quantity: string;
    unit_amount: {
      currency_code: string;
      value: string;
    };
    description?: string;
    tax?: {
      name: string;
      percent: string;
    };
  }>;
  note?: string;
  terms_and_conditions?: string;
  memo?: string;
  payment_term?: {
    term_type: 'DUE_ON_RECEIPT' | 'DUE_ON_DATE' | 'NET_10' | 'NET_15' | 'NET_30' | 'NET_45' | 'NET_60' | 'NET_90';
    due_date?: string;
  };
}

create_payout

处理批量付款。

{
  sender_batch_header: {
    sender_batch_id: string;
    email_subject?: string;
    recipient_type?: string;
  };
  items: Array<{
    recipient_type: string;
    amount: {
      value: string;
      currency: string;
    };
    receiver: string;
    note?: string;
  }>;
}

错误处理

服务器实现了全面的错误处理机制：

• 输入验证：带有具体信息的详细验证错误
• PayPal API 错误：包含 PayPal 错误详情的结构化错误响应
• 网络错误：针对暂时性网络问题的重试逻辑
• 认证错误：自动刷新令牌并提供清晰的错误消息
• 速率限制：针对 API 速率限制的退避策略

安全注意事项

• 所有敏感数据都经过验证和清理
• 通过 OAuth 2.0 与 PayPal 进行身份验证
• 通过环境变量进行安全凭据管理
• 对所有 API 参数进行输入验证
• 错误消息不暴露敏感信息

开发

构建

npm run build

以开发模式运行

npm run dev

测试

npm test

代码检查

npm run lint

格式化

npm run format

贡献

1. 分叉仓库
2. 创建一个功能分支
3. 提交你的更改
4. 推送到该分支
5. 创建一个拉取请求

许可证

MIT 许可证