mcpField
M
mcp-banco-do-brasil

mcp-banco-do-brasil

本地服务
github.com/codespar金融数据2754 周前更新
代码仓库

关于 mcp-banco-do-brasil

mcp-banco-do-brasil 是巴西 Banco do Brasil 银行 API 的 MCP 服务，涵盖 Pix、Cobrança（boleto）、活期账户与对账单等功能。适合需要直接对接 BB 而非通过支付服务商处理高频 Pix 与 boleto 业务的商户。当前版本为 alpha，部分接口路径尚未经官方文档验证。

主要功能

  1. 01提供 Pix 即时收费、查询与退款
  2. 02支持 DICT 密钥查询、登记与删除
  3. 03开具、查询与撤销 boleto
  4. 04查询活期账户余额与交易明细
  5. 05采用 OAuth2 与 mTLS 认证方式

适用场景

  1. 01商户直接通过 BB 生成 Pix 收款码
  2. 02核对 BB 活期账户的交易明细
  3. 03在付款前验证收款方 DICT 密钥信息

MCP 相关

该项目是 MCP 服务，向 MCP 客户端暴露 13 个 BB 相关工具，如 create_pix_cob、register_boleto 和 get_statement。

配置

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

mcp.json · 通用配置
{
  "mcpServers": {
    "codespar-mcp-banco-do-brasil": {
      "command": "npx",
      "args": [
        "-y",
        "@codespar/mcp-banco-do-brasil"
      ],
      "env": {
        "BB_CLIENT_ID": "<BB_CLIENT_ID>",
        "BB_CLIENT_SECRET": "<BB_CLIENT_SECRET>",
        "BB_DEVELOPER_APP_KEY": "<BB_DEVELOPER_APP_KEY>",
        "BB_CERT_PATH": "<BB_CERT_PATH>",
        "BB_KEY_PATH": "<BB_KEY_PATH>",
        "BB_ENV": "<BB_ENV>"
      }
    }
  }
}
启动命令npx -y @codespar/mcp-banco-do-brasil
需要配置的环境变量
BB_CLIENT_IDBanco do Brasil OAuth client_id issued via developers.bb.com.br after contract onboarding.
BB_CLIENT_SECRET密钥Banco do Brasil OAuth client_secret.
BB_DEVELOPER_APP_KEY密钥BB Developer App Key (gw-dev-app-key) — appended as a query param on most BB API calls.
BB_CERT_PATHAbsolute path to the mTLS client certificate (.crt or .pem). BACEN mandates mTLS for Pix v2 in production.
BB_KEY_PATH密钥Absolute path to the mTLS private key (.key or .pem).
BB_ENVEnvironment: 'sandbox' or 'production'. Defaults to 'sandbox'.

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

安装包
npm@codespar/mcp-banco-do-brasil0.1.0-alpha.5

工具

13

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

参数类型必填说明
txidstring否可选的商户提供 txid（26-35 位字母数字）。省略时由 BCB 分配。
payerobject否付款人身份信息（CPF/CNPJ + 姓名）
payer.namestring否
payer.documentstring否仅包含 CPF 或 CNPJ 数字
amountstring是以 BRL 主要单位表示的金额，例如 '99.90'
dict_keystring是收款方 DICT 密钥 — 必须是商户拥有的密钥
expires_innumber否二维码有效时长（秒，默认值为 3600）
descriptionstring否付款人可见的说明（solicitacaoPagador）

详细介绍

@codespar/mcp-banco-do-brasil

适用于 Banco do Brasil 的 MCP 服务——巴西最大的公共银行。

BB 在 Pix、Cobranças、Conta-Corrente、Open Finance 和 Arrecadação 等领域提供了全国范围内最广泛的公共银行 API 之一。处理大量 Pix 和 boleto 业务的商户会直接接入 BB，而不是通过 PSP。

状态：alpha（0.1.0-alpha.1）

BB 的开发者门户需要签约才能访问——只有完成商户入驻后，才能查看完整的 OpenAPI 规范。Pix 路径遵循 BACEN Pix v2 标准；boleto、账户和对账单路径则是根据 BB 的公开营销页面以及同业（Itaú、Santander、Bradesco）的惯例推测得出。所有未经验证的路径都在 src/index.ts 中标记为 TODO(verify)。在 0.1.x 期间，请固定使用精确版本。

工具（13）

工具用途
create_pix_cob创建即时 Pix 收款（cob），并生成二维码。
get_pix_cob根据 txid 获取即时 Pix 收款。
list_pix_cob按日期范围列出即时 Pix 收款（cob）。
create_pix_devolucao退还之前收到的 Pix。
get_pix_devolucao根据 endToEndId 和退款 ID 获取 Pix 退款。
resolve_dict_key将 DICT 密钥（CPF、CNPJ、电子邮件、电话、EVP）解析为所有者的账户数据，以便发送 Pix。
register_dict_key在商户拥有的 BB 账户上注册 DICT 密钥。
delete_dict_key删除商户拥有的 DICT 密钥。
register_boleto通过 BB Cobranças 开具 boleto。
get_boleto根据 nosso_numero 获取 boleto。
cancel_boleto在付款前取消（baixa）未结清的 boleto。
get_account_balance获取 BB conta-corrente（支票）账户的当前余额。
get_statement按日期范围获取 BB conta-corrente 的账户对账单交易记录。

安装

npm install @codespar/[email protected]

环境

BB_CLIENT_ID="..."             # OAuth client_id from developers.bb.com.br
BB_CLIENT_SECRET="..."         # OAuth client_secret
BB_DEVELOPER_APP_KEY="..."     # gw-dev-app-key — required on most calls
BB_CERT_PATH="/abs/path/client.crt"   # mTLS cert (production only)
BB_KEY_PATH="/abs/path/client.key"    # mTLS key  (production only)
BB_ENV="sandbox"                       # or "production" (default: sandbox)
BB_BASE_URL="..."                      # optional; default api.hm.bb.com.br (sandbox) / api.bb.com.br
BB_AUTH_URL="..."                      # optional; default https://oauth.hm.bb.com.br/oauth/token (sandbox) / oauth.bb.com.br

身份验证

  • OAuth2 client_credentials——令牌端点位于 oauth.{env}.bb.com.br。令牌会缓存至过期前约 60 秒。
  • mTLS——BACEN 要求在生产环境中使用 Pix v2。沙盒通常仅允许 TLS；在沙盒中证书和密钥为可选项，在生产环境中则为必需项。
  • gw-dev-app-key——BB API 网关密钥，会作为查询参数附加到所有调用中。

运行

npx @codespar/mcp-banco-do-brasil

企业版

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

许可证

MIT

评论

支持 Markdown

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。