mcp-paypal

Name: mcp-paypal
Author: codespar

本地服务

github.com/codespar金融数据2754 周前更新

代码仓库

关于 mcp-paypal

mcp-paypal 是面向 PayPal 的 MCP 服务，基于 PayPal REST API 提供全球收款、付款、订阅和争议处理等 19 个工具。适合已拥有 PayPal 商户账户、希望通过 Agent 处理结账与付款的 LatAm SaaS 或跨境市场。

主要功能

01提供 19 个 PayPal 相关工具
02支持订单创建、授权、捕获与退款
03支持批量付款与付款项查询
04支持订阅的创建、查询与取消
05支持争议查询与 Webhook 签名验证

适用场景

01通过 Agent 创建并捕获 PayPal 订单
02批量处理商户付款与查询付款状态
03管理订阅并处理争议索赔

MCP 相关

该项目是 MCP 服务，向 MCP 客户端暴露 PayPal REST API 的操作作为工具。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "codespar-mcp-paypal": {
      "command": "npx",
      "args": [
        "-y",
        "@codespar/mcp-paypal"
      ],
      "env": {
        "PAYPAL_CLIENT_ID": "<PAYPAL_CLIENT_ID>",
        "PAYPAL_CLIENT_SECRET": "<PAYPAL_CLIENT_SECRET>",
        "PAYPAL_ENV": "<PAYPAL_ENV>"
      }
    }
  }
}

启动命令npx -y @codespar/mcp-paypal

需要配置的环境变量

PAYPAL_CLIENT_IDPayPal REST app client id (from developer.paypal.com Apps & Credentials).

PAYPAL_CLIENT_SECRET密钥PayPal REST app client secret (OAuth2 client_credentials password).

PAYPAL_ENVPayPal environment. 'sandbox' (default, https://api-m.sandbox.paypal.com) or 'live' (https://api-m.paypal.com).

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@codespar/mcp-paypal0.1.2stdio

工具

收录的工具列表 · 更新于 2 周前

参数	类型	必填	说明
body	object	否	合并到请求中的其他 Order create 正文参数（application_context 等）。
intent	enum	是	在买家批准后立即捕获付款，或授权付款以便稍后捕获。CAPTURE \| AUTHORIZE
payment_source	object	否	可选的 payment_source 对象（例如 { paypal: { experience_context: { return_url, cancel_url } } } 或 { card: { ... } }）。
purchase_units	array	是	purchase_unit 对象数组。各項必须包含 amount: { currency_code, value }。可选项：reference_id、description、items、shipping、payee。
paypalRequestId	string	否	用于幂等性的可选 PayPal-Request-Id 标头。

详细介绍

@codespar/mcp-paypal

适用于 PayPal 的 MCP 服务 — 通过 PayPal REST API 处理全球付款和打款。

目标客户：面向全球销售的拉美 SaaS / 电商平台，已持有 PayPal 商家账户，并希望通过 Agent 驱动结账、打款、订阅和争议处理。

工具（19 个）

工具	用途
`create_order`	通过 POST /v2/checkout/orders 创建 PayPal Order。
`get_order`	通过 GET /v2/checkout/orders/{id} 按 ID 获取 PayPal Order。
`capture_order`	通过 POST /v2/checkout/orders/{id}/capture 收取已批准订单的款项。
`authorize_order`	通过 POST /v2/checkout/orders/{id}/authorize 授权已批准订单的付款。
`capture_authorization`	通过 POST /v2/payments/authorizations/{id}/capture 收取先前已授权的款项。
`refund_capture`	通过 POST /v2/payments/captures/{id}/refund 退还已收取的款项。
`void_authorization`	通过 POST /v2/payments/authorizations/{id}/void 作废（释放）尚未结算的授权。
`get_payment_details`	通过 GET /v2/payments/{type}/{id} 按 ID 获取付款对象。
`create_batch_payout`	通过 POST /v1/payments/payouts 创建批量打款。
`get_payout`	通过 GET /v1/payments/payouts/{batch_id} 按 ID 获取打款批次。
`get_payout_item`	通过 GET /v1/payments/payouts-item/{item_id} 按 ID 获取单笔打款。
`create_subscription`	通过 POST /v1/billing/subscriptions 创建计费订阅。
`get_subscription`	通过 GET /v1/billing/subscriptions/{id} 按 ID 获取订阅。
`cancel_subscription`	通过 POST /v1/billing/subscriptions/{id}/cancel 取消有效订阅。
`list_disputes`	通过 GET /v1/customer/disputes 列出争议。
`get_dispute`	通过 GET /v1/customer/disputes/{id} 按 ID 获取争议。
`accept_dispute_claim`	通过 POST /v1/customer/disputes/{id}/accept-claim 接受争议索赔的责任。
`list_webhooks`	通过 GET /v1/notifications/webhooks 列出为应用配置的 Webhook。
`verify_webhook_signature`	通过 POST /v1/notifications/verify-webhook-signature 验证 Webhook 事件签名。

安装

npm install @codespar/mcp-paypal

环境

PAYPAL_CLIENT_ID="..."       # REST app client id
PAYPAL_CLIENT_SECRET="..."   # REST app client secret (OAuth2)
PAYPAL_ENV="sandbox"         # 'sandbox' (default) or 'live'

端点：

sandbox -> https://api-m.sandbox.paypal.com
live -> https://api-m.paypal.com

身份验证

PayPal REST API 使用 OAuth2 client_credentials。服务会通过 Basic 身份验证，将 CLIENT_ID:CLIENT_SECRET 发送到 /v1/oauth2/token，并附带 grant_type=client_credentials；随后缓存 bearer token，直到过期前 60 秒，并按需刷新。

运行

# stdio (default — for Claude Desktop, Cursor, etc)
npx @codespar/mcp-paypal

# HTTP (for server-to-server testing)
MCP_HTTP=true MCP_PORT=3000 npx @codespar/mcp-paypal

说明

金额在 PayPal REST API 中以对象表示：{ "currency_code": "USD", "value": "10.50" }。金额值为十进制字符串。
对于接受 body 的工具，服务会原样转发任意 REST 正文中的字段，因此即使某个字段未包含在 MCP inputSchema 中，也可以传递 PayPal REST 参考文档中列出的任何字段。
对于付款收取 / 退款，如果提供了 PayPal-Request-Id 标头（幂等性），服务会将其转发。