mcp-picpay

Name: mcp-picpay
Author: codespar

本地服务

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

代码仓库

关于 mcp-picpay

mcp-picpay 是巴西数字钱包 PicPay Business 的 MCP 服务，面向需要在巴西开展收款、订阅和转账的商户与智能体开发者。它覆盖结账付款、Pix 二维码、订阅计划和钱包余额等接口。

主要功能

01创建付款、查询状态与退款
02生成静态和动态 PicPay 二维码
03管理订阅计划与订阅
04向 PicPay 用户发起 B2P 转账
05校验 webhook 回调的 seller token

适用场景

01为商户生成付款链接或二维码并跟踪订单状态
02管理定期订阅的计划与用户注册
03批量向 PicPay 用户付款并查询转账记录
04在处理回调前校验通知来源

MCP 相关

该服务以 MCP 工具形式暴露 PicPay 结账、订阅、转账和钱包接口，供 MCP 客户端调用。

配置

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

mcp.json · 通用配置

{
  "mcpServers": {
    "codespar-mcp-picpay": {
      "command": "npx",
      "args": [
        "-y",
        "@codespar/mcp-picpay"
      ],
      "env": {
        "PICPAY_TOKEN": "<PICPAY_TOKEN>",
        "PICPAY_SELLER_TOKEN": "<PICPAY_SELLER_TOKEN>",
        "PICPAY_BASE_URL": "<PICPAY_BASE_URL>"
      }
    }
  }
}

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

需要配置的环境变量

PICPAY_TOKEN密钥PicPay merchant integration token (sent as x-picpay-token header)

PICPAY_SELLER_TOKEN密钥PicPay seller token used to validate webhook callbacks (x-seller-token header)

PICPAY_BASE_URLPicPay ecommerce API base URL. Defaults to https://appws.picpay.com/ecommerce/public.

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

安装包

npm@codespar/mcp-picpay0.2.0-alpha.3stdio

工具

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

参数	类型	必填	说明
buyer	object	否	买家身份信息。根据 BCB 规定，必须提供 document（CPF）。
buyer.email	string	否
buyer.phone	string	否	E.164 或巴西格式（例如，+55 11 91234-5678）
buyer.document	string	是	CPF，仅包含数字或使用格式化形式
buyer.lastName	string	是
buyer.firstName	string	是
value	number	是	BRL 金额，小数格式（例如，100.50）。不是分。
expiresAt	string	否	ISO-8601 到期时间戳（例如，2026-12-31T23:59:59-03:00）
returnUrl	string	是	买家在 PicPay 应用中完成付款后重定向到的 URL。
callbackUrl	string	是	PicPay 在状态变更时向其发送 POST 请求的 HTTPS 端点。通过 x-seller-token 标头进行验证。
referenceId	string	是	商户端的订单唯一标识符。用于后续的状态查询／取消调用。

详细介绍

@codespar/mcp-picpay

适用于 PicPay Business 的 MCP 服务——这款巴西数字钱包拥有 6,000 多万用户。

PicPay 的 Checkout API 可让商家创建付款意向，由买家在 PicPay 应用内完成付款，并返回重定向 URL 和类似 Pix 的二维码。Recurrency API 则在此基础上增加了订阅计划。

工具（20）

工具	用途
`create_payment`	创建 PicPay 结账付款。
`get_payment_status`	根据 referenceId 获取付款状态。
`cancel_payment`	取消 PicPay 订单。
`create_plan`	创建订阅计划（Recurrency API）。
`list_plans`	列出为此商家注册的所有订阅计划。
`update_plan`	更新现有订阅计划。
`delete_plan`	删除订阅计划。
`create_subscription`	为买家开通订阅计划。
`get_subscription`	根据 ID 获取订阅。
`cancel_subscription`	取消有效订阅。
`validate_notification`	通过将 x-seller-token 标头与 PI... 进行比较，验证收到的 webhook 回调是否来自 PicPay。
`refund_payment`	为已付款的 PicPay 订单退款，也可选择部分退款。
`create_b2p_transfer`	创建个人对企业（B2P）转账：将资金从商家钱包转入由... 标识的 PicPay 用户。
`get_b2p_transfer`	根据 referenceId 获取 B2P 转账状态。
`create_batch_payment`	在单个请求中提交一批 B2P 转账。
`list_transactions`	列出指定日期范围内的商家交易（付款和转账）。
`get_wallet_balance`	获取商家当前 PicPay 钱包余额（以 BRL 计的可用金额和冻结金额）。
`generate_static_qrcode`	生成静态 PicPay Pay 二维码，供店内使用或重复使用。
`generate_dynamic_qrcode`	生成具有固定金额和可选过期时间的动态 PicPay Pay 二维码。
`create_payment_link`	创建可分享的 PicPay 付款链接。

安装

npm install @codespar/mcp-picpay@alpha

环境

PICPAY_TOKEN="..."          # Merchant integration token (x-picpay-token header)
PICPAY_SELLER_TOKEN="..."   # Seller token used to validate webhook callbacks
PICPAY_BASE_URL="..."       # Optional. Defaults to https://appws.picpay.com/ecommerce/public

身份验证

每个请求都会发送：

Content-Type: application/json
x-picpay-token: <PICPAY_TOKEN>

PicPay webhook 回调会携带 x-seller-token: <PICPAY_SELLER_TOKEN>。请先使用 validate_notification 工具（或自行比较标头）再信任载荷，然后通过 get_payment_status 获取权威状态。

运行

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

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

状态

0.1.0-alpha.1。核心结账端点（/payments、/payments/{ref}/status、/payments/{ref}/cancellations）已根据 PicPay 的公开文档验证。Recurrency（计划和订阅）端点根据文档中的路径格式提供，但字段级架构（频率枚举值、订阅响应）应在投入生产使用前通过实时 API 确认。