Payman API MCP Server

Payman API MCP 服务

一个 MCP（Model Context Protocol）服务，可与 Payman AI 的支付 API 无缝集成，让 AI 助手通过自然语言创建收款方、搜索现有收款方、发送付款和查询余额。

概述

此 MCP 服务将 Payman AI 的支付功能公开为工具，供 Claude 等大模型应用使用。它使 AI 助手能够执行以下操作：

• 设置用于身份验证的 API 密钥
• 创建不同类型的收款方（TEST_RAILS、US_ACH、CRYPTO_ADDRESS）
• 向已注册的收款方发送付款
• 根据各种条件搜索收款方
• 查询账户余额

此实现遵循 Model Context Protocol（MCP）标准，可确保与任何兼容 MCP 的客户端兼容。

功能

• 安全的 API 身份验证：在会话中安全地管理 API 密钥
• 多种收款方类型：
  • 用于测试的 TEST_RAILS 收款方
  • 用于美国银行转账的 US_ACH 收款方
  • 用于加密货币交易的 CRYPTO_ADDRESS 收款方
• 支付操作：
  • 使用自定义金额和备注发送付款
  • 获取当前余额
• 搜索功能：
  • 按姓名、联系信息、账户详情等搜索收款方
• 错误处理：为所有 API 操作提供全面的错误处理
• 安全传输：支持 stdio 和 SSE（Server-Sent Events）传输方式

前置条件

• Node.js（v14 或更高版本）
• npm 或 yarn
• Payman AI API 密钥

安装

通过 Smithery 安装

通过 Smithery 自动为 Claude Desktop 安装 payman_mcp：

npx -y @smithery/cli install @hrishi0102/payman_mcp --client claude

1. 克隆仓库：

   git clone https://github.com/yourusername/payman-mcp-server.git
   cd payman-mcp-server
   

2. 安装依赖：

   npm install
   # OR
   yarn install
   

3. 构建 TypeScript 代码：

   npm run build
   # OR
   yarn build
   

配置

此服务不需要任何配置文件。可在运行时使用 set-api-key 工具设置 API 密钥。

运行服务

标准输入/输出模式（用于 Claude Desktop 等）

以 stdio 模式运行服务，该模式兼容 Claude Desktop 和类似的 MCP 客户端：

检查服务是否已正确设置：

node /ABSOLUTE/PATH/TO/PARENT/FOLDER/payman-mcp/build/payman-server.js

如果一切正常，现在即可将 Payman MCP 服务添加到任何客户端。

• 对于 Claude Desktop： 此处
• 对于 Cursor： 此处

Server-Sent Events（SSE）模式（用于 Web 集成）

如需使用 SSE 传输方式运行服务（需要额外依赖：express 和 cors）：

node build/payman-server-sse.js

这将在端口 3001 上启动 Web 服务，并提供以下端点：

• /sse - 用于服务端到客户端通信的 SSE 端点
• /messages - 用于客户端到服务端消息的端点

与 MCP 客户端集成

Claude Desktop

1. 打开 Claude Desktop 配置文件：

   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json

2. 添加服务配置：

   {
     "mcpServers": {
       "payman": {
         "command": "node",
         "args": ["/ABSOLUTE/PATH/TO/payman-mcp-server/build/payman-server.js"]
       }
     }
   }
   

3. 重启 Claude Desktop

其他 MCP 客户端

对于 Cursor 等其他 MCP 客户端，请参阅其各自的文档，了解如何添加 MCP 服务。

使用指南

服务连接到 MCP 客户端后，即可使用以下工具：

设置 API 密钥

首先，需要设置 Payman API 密钥：

Please use the set-api-key tool with my Payman API key: YOUR_API_KEY_HERE

创建收款方

Test Rails 收款方

Create a test payee named "Test User" with the tag "test"

US ACH 收款方

Create a US ACH payee with these details:
- Name: John Doe
- Account Type: checking
- Account Number: 12345678
- Routing Number: 123456789
- Account Holder Name: John Doe
- Account Holder Type: individual

Crypto 收款方

Create a crypto payee with:
- Name: Crypto Wallet
- Address: 0x1234567890abcdef
- Chain: ethereum
- Currency: ETH

发送付款

Send a payment of 100 to payee ID "pay_123abc" with the memo "Monthly service"

搜索收款方

Search for all payees with the name "John"

查询余额

What's my current balance?

工具参考

set-api-key

设置用于身份验证的 Payman API 密钥。

• 参数：
  • apiKey（字符串）：Payman API 密钥

create-test-rails-payee

创建用于测试的 TEST_RAILS 收款方。

• 参数：
  • name（string）：收款方名称
  • type（string）："TEST_RAILS"（默认值）
  • tags（string[]）：收款方的可选标签

create-us-ach-payee

创建用于银行转账的 US_ACH 收款方。

• 参数：
  • type（string）："US_ACH"（默认值）
  • accountType（enum）："checking" 或 "savings"
  • accountNumber（string）：银行账号
  • routingNumber（string）：银行路由号码
  • accountHolderName（string）：账户持有人姓名
  • accountHolderType（enum）："individual" 或 "business"
  • name（string）：该收款方的名称
  • 以及其他可选参数（tags、contactDetails）

create-crypto-payee

创建用于加密货币付款的 CRYPTO_ADDRESS 收款方。

• 参数：
  • type（string）："CRYPTO_ADDRESS"（默认值）
  • address（string）：加密货币地址
  • chain（string）：要使用的区块链
  • currency（string）：加密货币／代币
  • name（string）：该收款方的名称
  • 以及其他可选参数（tags、contactDetails）

send-payment

向收款方付款。

• 参数：
  • payeeId（string）：收款方 ID
  • amountDecimal（number）：付款金额
  • walletId（string，可选）：要使用的特定钱包
  • memo（string，可选）：付款备注
  • metadata（object，可选）：其他元数据

search-payees

根据各种条件搜索收款方。

• 参数：多个可选搜索参数
  • name、contactEmail、accountNumber 等

get-balance

获取当前账户余额。

• 参数：无

错误处理

所有工具都包含适当的错误处理，并会在以下情况下返回详细的错误消息：

• 尚未设置 API 密钥
• API 请求失败
• 提供了无效参数
• 出现网络问题

安全注意事项

• API 密钥会在会话期间存储在内存中

• 服务不会将任何凭据持久化到磁盘

• 所有对 Payman API 的请求都会使用正确的授权标头

• 模型上下文协议：MCP 规范

• Payman AI：支付 API

• Zod：输入验证