MCP server

npm payzu-mcp-pix GitHub 仓库 SKILL.md(轻量替代)

MCP 是一个开放协议,让 AI 助手通过 JSON-RPC 调用外部工具。payzu-mcp-pix 暴露了 Pix Processamento API 的 29 个精选 tools,具备可读性强的命名(pix.create、account.balance 等)、类型校验和一致的错误处理。

何时用 MCP、SKILL.md 还是 SDK

场景	使用
AI 在你的 PayZu 账户上执行真实调用(创建 Pix、查看余额等)	MCP
AI 生成代码后你粘贴到自己的应用	SKILL.md
你的生产应用与 PayZu 通信	SDK(`npm install payzu-pix`)

安装

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json(macOS)或 %APPDATA%\Claude\claude_desktop_config.json(Windows):

{
  "mcpServers": {
    "payzu-pix": {
      "command": "npx",
      "args": ["-y", "payzu-mcp-pix"],
      "env": {
        "PAYZU_TOKEN": "<你的-dashboard-token>"
      }
    }
  }
}

重启 Claude Desktop。问一句"我的 PayZu 余额是多少?"试试,Claude 会自动调用 account.balance。

Cursor

项目里的 .cursor/mcp.json(或全局 ~/.cursor/mcp.json):

{
  "mcpServers": {
    "payzu-pix": {
      "command": "npx",
      "args": ["-y", "payzu-mcp-pix"],
      "env": { "PAYZU_TOKEN": "..." }
    }
  }
}

Continue、Codeium 及其他

配置一致(都遵循 MCP 标准)。详见包的 README。

配置

Env var	必填	默认值	说明
`PAYZU_TOKEN`	是	,	来自 abrirconta.payzu.com.br 的 Bearer token
`PAYZU_API_URL`	否	`https://api.payzu.processamento.com/v1`	whitelabel 场景下覆盖

tools 清单(29 个)

所有名称采用 snake_case,按域名空间分组。每个 tool 的 description 包含直达文档对应 endpoint 页面的链接。

Pix 收款(4)

Tool	HTTP
`pix.create`	`POST /pix`
`pix.get`	`GET /pix`
`pix.qr_code`	`GET /pix/qr-code/{id}`
`pix.proof`	`GET /proof/{id}`

提现(6)

Tool	HTTP
`withdraw.create`	`POST /withdraw`
`withdraw.get`	`GET /withdraw`
`withdraw.by_qr`	`POST /withdraw/qrcode`
`withdraw.read_qr`	`POST /pix/qrcode/read`
`withdraw.dict`	`GET /pix-key/{key}`
`withdraw.proof`	`GET /withdraw/proof/{id}`

内部转账(2)

Tool	HTTP
`internal_transfer.create`	`POST /internal-transfer`
`internal_transfer.get`	`GET /internal-transfer`

账户(2)

Tool	HTTP
`account.profile`	`GET /user`
`account.balance`	`GET /user/balance`

报表(6)

Tool	HTTP
`reports.list_transactions`	`GET /user/transactions`
`reports.get_transaction`	`GET /user/transactions/{id}`
`reports.create_csv`	`POST /user/report`
`reports.list_jobs`	`GET /user/reports`
`reports.get_job`	`GET /user/report/{id}`
`reports.download`	`GET /user/report/{id}/download`

callbacks(4)

Tool	HTTP
`callbacks.list`	`GET /user/callbacks`
`callbacks.get`	`GET /user/callback/{id}`
`callbacks.resend`	`POST /user/callback/{id}/resend`
`callbacks.resend_bulk`	`POST /user/callbacks/resend`

MED 违规(5)

Tool	HTTP
`infractions.list`	`GET /infractions`
`infractions.get`	`GET /infractions/{id}`
`infractions.create_defense`	`POST /infractions/{id}/defense`
`infractions.list_defenses`	`GET /infractions/{id}/defenses`
`infractions.get_defense`	`GET /infractions/{id}/defense/{defenseId}`

默认约定

金额以雷亚尔小数形式传入,tool 拒绝分单位(9990 会触发校验错误;必须是 99.90)。
创建类调用必须传 clientReference(idempotência)。
创建类调用必须传 callbackUrl(否则没人通知你状态)。
自动重试 5xx/429,采用指数退避 + jitter(最多 3 次)。
错误信息包含 requestId,如需协助直接复制给支持团队。
零 admin endpoints,仅暴露公开/客户端层面。

使用示例(Claude Desktop)

配置完成后,可以这样对话:

"创建一个 R$ 50 的 PayZu 收款,reference 为 order-abc"

Claude 会选择 pix.create,校验参数并调用 API。在 chat 里返回 id、qrCodeText 和 qrCodeUrl。

"我有多少余额?"

Claude 调用 account.balance 并返回数字。

"列出最近 10 条已取消的交易"

Claude 调用 reports.list_transactions,传入 status: CANCELED, limit: 10。

支持

提交 bug 完整文档 PayZu 支持

MCP server

On this page