# PayPal-MCP服务
## 基本信息
- Slug: `arbuthnot-eth-paypal-mcp`
- Source: modelscope
- Publisher: @arbuthnot-eth/PayPal-MCP
- Categories: 金融 / ecommerce-and-retail
- Hosted: No
- License: Apache License 2.0
- Source URL: https://www.modelscope.cn/mcp/servers/@arbuthnot-eth/PayPal-MCP
## 简介
一种模型上下文协议服务器，提供与PayPal API的全面集成，通过标准化接口实现与支付处理、开票、订阅管理和业务运营的无缝交互。
## 安装提示

```bash
## 安装 ### 前提条件 - Node.js 16.x 或更高版本 - 拥有 API 凭证的 PayPal 开发者账号 ### 手动安装 1. 克隆仓库 ```bash git clone https://github.com/arbuthnot-eth/PayPal-MCP.git cd PayPal-MCP
```

## MCP Server 详情

# PayPal MCP 服务器

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue.svg)](https://www.typescriptlang.org/)
[![Node.js](https://img.shields.io/badge/Node.js-16%2B-green.svg)](https://nodejs.org/)

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

## 功能

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

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

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

## 架构

```mermaid
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. 克隆仓库
   ```bash
   git clone https://github.com/arbuthnot-eth/PayPal-MCP.git
   cd PayPal-MCP
   ```

2. 安装依赖
   ```bash
   npm install
   ```

3. 构建项目
   ```bash
   npm run build
   ```

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

   ```json
   {
     "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

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

```typescript
{
  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 中创建一个新订单。

```typescript
{
  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

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

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


#### create_subscription

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

```typescript
{
  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

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

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


#### create_invoice

生成一张新的发票。

```typescript
{
  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

处理批量付款。

```typescript
{
  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 参数进行输入验证
- 错误消息不暴露敏感信息

## 开发

### 构建

```bash
npm run build
```


### 以开发模式运行

```bash
npm run dev
```


### 测试

```bash
npm test
```


### 代码检查

```bash
npm run lint
```


### 格式化

```bash
npm run format
```


## 贡献

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

## 许可证

MIT 许可证