mcp-pix-bcb

@codespar/mcp-pix-bcb

面向 Pix BCB 的 MCP 服务 — 巴西中央银行官方 Pix API

快速开始

Claude Desktop

添加到 ~/.config/claude/claude_desktop_config.json：

{
  "mcpServers": {
    "pix-bcb": {
      "command": "npx",
      "args": ["-y", "@codespar/mcp-pix-bcb"],
      "env": {
        "PIX_BASE_URL": "https://pix.example.com/api/v2",
        "PIX_CLIENT_ID": "your-client-id",
        "PIX_CLIENT_SECRET": "your-client-secret",
        "PIX_CERT_PATH": "/path/to/certificate.pem"
      }
    }
  }
}

Claude Code

claude mcp add pix-bcb -- npx @codespar/mcp-pix-bcb

Cursor / VS Code

添加到 .cursor/mcp.json 或 .vscode/mcp.json：

{
  "servers": {
    "pix-bcb": {
      "command": "npx",
      "args": ["-y", "@codespar/mcp-pix-bcb"],
      "env": {
        "PIX_BASE_URL": "https://pix.example.com/api/v2",
        "PIX_CLIENT_ID": "your-client-id",
        "PIX_CLIENT_SECRET": "your-client-secret",
        "PIX_CERT_PATH": "/path/to/certificate.pem"
      }
    }
  }
}

工具（18 个）

工具	用途
create_cob	创建即时 Pix 收费（cobranca imediata）
get_cob	根据 txid 获取即时收费详情
list_cobs	按日期范围和筛选条件列出即时收费
update_cob	修改现有的即时收费（PATCH /cob/{txid}）。
create_cobv	创建到期日 Pix 收费（cobranca com vencimento）
list_cobv	按日期范围列出到期日收费（cobv）
update_cobv	修改现有的到期日收费（PATCH /cobv/{txid}）
get_pix	根据 e2eid（endToEndId）获取收到的 Pix 付款
list_pix_received	按日期范围列出收到的 Pix 付款
create_devolucao	为收到的 Pix 申请退款（devolução）（PUT /pix/{e2eid}/devolucao/{id}）
get_devolucao	根据 e2eid 和退款 ID 获取退款详情（GET /pix/{e2eid}/devolucao/{id}）
create_pix_key	在 DICT 中注册 Pix 密钥（需要 PSP 支持）
get_pix_key	在 DICT 中查询 Pix 密钥
list_pix_keys	列出此 PSP 中经身份验证账户持有的所有 Pix 密钥
request_key_portability	将 Pix 密钥从其他 PSP 转入此 PSP（DICT 密钥可携流程）
resolve_key_claim	处理待处理的 DICT 密钥申诉（确认或取消）— POST /dict/keys/claims/{id}/resolve
set_webhook	为指定 Pix 密钥配置 webhook URL（PUT /webhook/{chave}）。
delete_webhook	移除为 Pix 密钥配置的 webhook（DELETE /webhook/{chave}）

身份验证

Pix BCB API 使用基于客户端凭证的 OAuth2 和 mTLS。每个 PSP（银行）都有自己的基础 URL 和证书要求。

沙盒 / 测试

沙盒是否可用取决于 PSP（支付服务提供商）。请联系你的银行，获取接入认证环境的权限。

获取凭证

1. 前往 Pix API 文档（BCB）
2. 向你的 PSP（银行）注册以获取 API 访问权限
3. 获取 OAuth2 客户端凭证和 mTLS 证书
4. 设置环境变量

环境变量

变量	必需	说明
PIX_BASE_URL	是	PSP API 基础 URL（例如，https://pix.example.com/api/v2）
PIX_CLIENT_ID	是	OAuth2 客户端 ID
PIX_CLIENT_SECRET	是	OAuth2 客户端密钥
PIX_CERT_PATH	否	mTLS 证书路径（.pem 或 .p12）

路线图

v0.2（计划中）

• create_location — 创建 Pix 位置（载荷 URL）
• get_location — 获取 Pix 位置详情
• list_locations — 列出所有 Pix 位置
• create_devolucao — 创建 Pix 退款（devolucao）
• get_devolucao — 获取 Pix 退款详情

v0.3（计划中）

• create_cobv_batch — 创建一批到期日 Pix 收费（cobv）
• webhook_management — 注册、获取和删除 Pix webhook

想要参与贡献？提交 PR 或请求添加工具。

链接

• Pix API 规范（BCB）
• 巴西中央银行
• MCP Dev LATAM
• 落地页

企业版

需要为 Agent 付款提供治理、预算限额和审计跟踪？CodeSpar Enterprise 在这些 MCP 服务之上提供策略引擎、付款路由和合规模板。

许可证

MIT