PayPal MCP 服务器

由 DynamicEndpoints 维护 - 联系方式：kameron@dynamicendpoints.com

一个提供与 PayPal API 集成的 Model Context Protocol (MCP) 服务器。此服务器通过标准化接口实现与 PayPal 的支付处理、发票和业务管理功能的无缝交互。

架构

graph TB
    subgraph "MCP Environment"
        Client[MCP Client]
        Server[PayPal MCP Server]
        Validation[Input Validation]
        Auth[OAuth Authentication]
    end

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

    Client --> |Request| Server
    Server --> |Response| Client
    Server --> Validation
    Server --> Auth
    Auth --> |Access Token| PayPal
    
    Server --> Orders
    Server --> Payments
    Server --> Payouts
    Server --> Invoicing
    Server --> Products
    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

功能

• 支付处理

  • 创建和管理订单
  • 处理付款
  • 处理支付令牌
  • 管理争议

• 业务操作

  • 创建和管理产品
  • 生成发票
  • 处理支出
  • 处理合作伙伴推荐

• 用户管理

  • 身份验证
  • 用户信息检索
  • Web 个人资料管理

安装

通过 Smithery 安装

要通过 Smithery 自动安装适用于 Claude Desktop 的 PayPal MCP 服务器：

npx -y @smithery/cli install @DynamicEndpoints/Paypal-MCP --client claude

手动安装

1. 克隆仓库
2. 安装依赖项：

   npm install
   

3. 构建项目：

   npm run build
   

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

   {
     "mcpServers": {
       "paypal": {
         "command": "node",
         "args": ["path/to/paypal-server/build/index.js"],
         "env": {
           "PAYPAL_CLIENT_ID": "your_client_id",
           "PAYPAL_CLIENT_SECRET": "your_client_secret"
         },
         "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;
  }>;
}

create_payment

创建直接支付。

{
  intent: string;
  payer: {
    payment_method: string;
    funding_instruments?: Array<{
      credit_card?: {
        number: string;
        type: string;
        expire_month: number;
        expire_year: number;
        cvv2: string;
        first_name: string;
        last_name: string;
      };
    }>;
  };
  transactions: Array<{
    amount: {
      total: string;
      currency: string;
    };
    description?: 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;
    };
  }>;
}

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;
  }>;
}

用户和个人资料管理

get_userinfo

检索用户信息。

{
  access_token: string;
}

create_web_profile

创建 Web 体验个人资料。

{
  name: string;
  presentation?: {
    brand_name?: string;
    logo_image?: string;
    locale_code?: string;
  };
  input_fields?: {
    no_shipping?: number;
    address_override?: number;
  };
  flow_config?: {
    landing_page_type?: string;
    bank_txn_pending_url?: string;
  };
}

使用示例

创建订单

const result = await mcpClient.useTool('paypal', 'create_order', {
  intent: 'CAPTURE',
  purchase_units: [{
    amount: {
      currency_code: 'USD',
      value: '100.00'
    },
    description: 'Premium Subscription'
  }]
});

生成发票

const result = await mcpClient.useTool('paypal', 'create_invoice', {
  invoice_number: 'INV-2024-001',
  reference: 'REF-2024-001',
  currency_code: 'USD',
  recipient_email: 'customer@example.com',
  items: [{
    name: 'Consulting Services',
    quantity: '1',
    unit_amount: {
      currency_code: 'USD',
      value: '500.00'
    }
  }]
});

处理支出

const result = await mcpClient.useTool('paypal', 'create_payout', {
  sender_batch_header: {
    sender_batch_id: 'Payroll_2024_001',
    email_subject: 'You have received a payment'
  },
  items: [{
    recipient_type: 'EMAIL',
    amount: {
      value: '1000.00',
      currency: 'USD'
    },
    receiver: 'employee@example.com',
    note: 'Monthly salary payment'
  }]
});

错误处理

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

• 输入验证错误，并附带详细信息
• PayPal API 错误，并附带响应详情
• 网络和认证错误
• 限流和超时处理

安全性考虑

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

开发

构建

npm run build

测试

npm test

调试

服务器输出详细的日志以帮助调试：

• 认证问题
• API 调用失败
• 验证错误
• 请求/响应详情

贡献

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

许可证

MIT 许可证