paypay-mcp

paypay-mcp

适用于 PayPay Open Payment API 的 Model Context Protocol 服务。

可与 Claude Desktop、Claude Code、Cursor、Windsurf、Zed、ChatGPT Apps SDK 及其他兼容 MCP 的客户端配合使用。工具描述提供英语和日语版本。

状态

v0.2.x — 已可用于生产环境，但尚未经过大规模实战检验。

设置 PAYPAY_ENV=production 并使用已获批准的商户凭据后，该服务即可与 PayPay 的生产环境 Open Payment API 正常运行。目前尚未处理过有实际意义的真实交易量。如果要通过它处理真实付款，请固定版本并先审查源代码。

工具

工具	描述
create_qr_code	创建动态 PayPay 二维码。返回付款 URL、深层链接和渲染后的 PNG。
get_payment_details	获取付款的当前状态。
wait_for_payment	轮询，直到付款进入终止状态。
delete_qr_code	在付款前使二维码失效。
refund_payment	全额或部分退款。除非设置 PAYPAY_ENABLE_REFUNDS=true，否则默认禁用。
cancel_payment	当付款状态不明确（超时或错误）时取消付款。除非设置 PAYPAY_ENABLE_CANCELS=true，否则默认禁用。

提示词

accept_single_payment、refund_last_payment、debug_stuck_payment。

资源

URI	描述
paypay://docs/opa-reference	PayPay OPA API 的端点映射、身份验证方案和状态说明。
paypay://docs/payment-states	付款生命周期以及取消与退款的决策规则。
paypay://config/current	当前配置的非敏感信息视图（env、merchantId、baseUrl、transport）。

安装

一键安装：

或通过 npm 安装：

npm install -g paypay-mcp

配置

凭据可从 PayPay Developer Dashboard 获取。

变量	必填	描述
PAYPAY_API_KEY	是	OPA API Key ID
PAYPAY_API_SECRET	是	OPA API Key Secret
PAYPAY_MERCHANT_ID	是	Merchant ID
PAYPAY_ENV	否	sandbox（默认）或 production
PAYPAY_ENABLE_REFUNDS	否	设置为 true 以启用 refund_payment。默认禁用。
PAYPAY_ENABLE_CANCELS	否	设置为 true 以启用 cancel_payment。默认禁用。
MCP_TRANSPORT	否	stdio（默认）或 http
MCP_HTTP_PORT	否	MCP_TRANSPORT=http 时使用的端口。默认为 3000。
MCP_HTTP_HOST	否	绑定地址。默认为 127.0.0.1。公开绑定需要设置 MCP_AUTH_TOKEN。
MCP_AUTH_TOKEN	否	设置后，传入的 HTTP 请求必须提供 Bearer 令牌。非环回绑定时为必填项。
MCP_HTTP_ALLOWED_ORIGINS	否	以逗号分隔的 CORS 允许列表。默认：无。

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "paypay": {
      "command": "npx",
      "args": ["-y", "paypay-mcp"],
      "env": {
        "PAYPAY_API_KEY": "a_...",
        "PAYPAY_API_SECRET": "...",
        "PAYPAY_MERCHANT_ID": "...",
        "PAYPAY_ENV": "sandbox"
      }
    }
  }
}

Claude Code

claude mcp add paypay -e PAYPAY_API_KEY=... -e PAYPAY_API_SECRET=... -e PAYPAY_MERCHANT_ID=... -- npx -y paypay-mcp

Cursor

将其添加到 ~/.cursor/mcp.json，格式与 Claude Desktop 相同。

远程托管

以 HTTP 模式运行。公开绑定必须设置 MCP_AUTH_TOKEN；否则服务将拒绝启动。

MCP_TRANSPORT=http \
  MCP_HTTP_HOST=0.0.0.0 \
  MCP_AUTH_TOKEN="$(openssl rand -hex 32)" \
  MCP_HTTP_ALLOWED_ORIGINS="https://claude.ai,https://your-app.example.com" \
  PAYPAY_ENV=sandbox \
  PAYPAY_API_KEY=... PAYPAY_API_SECRET=... PAYPAY_MERCHANT_ID=... \
  npx paypay-mcp

端点：POST http(s)://<host>:3000/mcp（Streamable HTTP 传输）。客户端发送 Authorization: Bearer <MCP_AUTH_TOKEN>。默认关闭 CORS。

本地测试时可以省略身份验证令牌；服务将绑定到 127.0.0.1，且只接受环回连接。

环境

默认使用 Sandbox。生产环境需要完成 PayPay 商户入驻（企业验证和签约），并且必须通过显式设置 PAYPAY_ENV=production 来启用。

限制

• 金额以整数日元计。
• 支付尝试后的次日 JST 00:14:59 之前可以取消支付。此后请使用退款。
• 单笔订单可以进行多次部分退款，每次退款都必须使用唯一的 merchantRefundId，退款总额不得超过商户配置的上限。
• 需要 TLS 1.2+（Node 20+）。

开发

git clone https://github.com/mrslbt/paypay-mcp.git
cd paypay-mcp
npm install
cp .env.example .env
npm run dev
npm test
npm run smoke
npm run build

路线图

v0.2：PreAuth + Capture、ContinuousPayments、DirectDebit、AccountLink QR、Webhook 签名验证、对账工具。

v0.3：Native Payment（App Invoke + 用户 JWT 身份验证）、Visa 合作端点、OpenTelemetry 跟踪。

安全

此服务可通过 PayPay OPA API 转移真实资金。主要安全措施：

• 默认禁用退款和取消工具。 只有设置 PAYPAY_ENABLE_REFUNDS=true 或 PAYPAY_ENABLE_CANCELS=true 时，才会注册 refund_payment 和 cancel_payment。仅在可信的 Agent 场景中启用，确保工具输入不会受到不可信内容的影响。
• 默认使用 Sandbox。 生产环境需要显式设置 PAYPAY_ENV=production，并且完成 PayPay 商户入驻。请务必先在 Sandbox 中测试。
• 每次调用都使用唯一的 merchantPaymentId 和 merchantRefundId。 PayPay 会根据这些 ID 去重；重复使用可能导致失败，也可能会针对较早的支付执行操作。每笔新支付或退款都要生成新的 ID。
• 工具带有 MCP 安全注解。 只读工具（get_payment_details、wait_for_payment）标记为 readOnlyHint；资金转移和破坏性工具（refund_payment、cancel_payment、delete_qr_code）标记为 destructiveHint，兼容的客户端可据此在调用前向你发出警告。这些仅为提示，真正的保护措施是上述启用限制。

即使启用了这些限制，在批准工具调用前也要审查任何涉及资金转移的请求。将来自模型输出的工具输入视为不可信内容。

免责声明

这是一个非官方的社区构建 MCP 服务，与 PayPay Corporation 无关联，未获其认可或赞助。PayPay 是其各自所有者的注册商标。使用风险由你自行承担。对于因误用、提示词注入或错误导致的资金损失，作者不承担任何责任。

许可证

MIT