About mcp-banco-do-brasil
mcp-banco-do-brasil is an MCP server for the Banco do Brasil bank APIs, covering Pix, boleto charges, checking accounts and statements. It is aimed at merchants who integrate directly with the bank rather than through a payment provider. The package is alpha, and several endpoint paths are unverified against the official specs.
Key features
- 01Creates, retrieves and refunds immediate Pix charges
- 02Resolves, registers and deletes DICT keys
- 03Issues, looks up and cancels boletos
- 04Retrieves checking account balance and statements
- 05Uses OAuth2 client credentials with optional mTLS
Use cases
- 01Generating Pix payment QR codes directly through BB
- 02Reviewing checking account transactions over a date range
- 03Checking a recipient's DICT key before sending a Pix
MCP support
This project is an MCP server that exposes 13 Banco do Brasil tools to MCP clients, such as create_pix_cob, register_boleto and get_statement.
Configuration
Local server config is the same for every client. Copy it into your client’s MCP config file.
npx -y @codespar/mcp-banco-do-brasilBB_CLIENT_IDBanco do Brasil OAuth client_id issued via developers.bb.com.br after contract onboarding.BB_CLIENT_SECRETSecretBanco do Brasil OAuth client_secret.BB_DEVELOPER_APP_KEYSecretBB 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_PATHSecretAbsolute path to the mTLS private key (.key or .pem).BB_ENVEnvironment: 'sandbox' or 'production'. Defaults to 'sandbox'.Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.
Tools
13Saved tool list · updated 2w ago
| Parameter | Type | Required | Description |
|---|---|---|---|
| txid | string | No | Optional merchant-supplied txid (26-35 alphanumeric). Omit to have BCB assign one. |
| payer | object | No | Payer identification (CPF/CNPJ + name) |
| payer.name | string | No | |
| payer.document | string | No | CPF or CNPJ digits only |
| amount | string | Yes | Amount in BRL major units, e.g. '99.90' |
| dict_key | string | Yes | Recebedor DICT key — must be a key owned by the merchant |
| expires_in | number | No | QR lifetime in seconds (default 3600) |
| description | string | No | Payer-visible description (solicitacaoPagador) |
Details
From the project README@codespar/mcp-banco-do-brasil
MCP server for Banco do Brasil — Brazil's top public bank.
BB exposes one of the broadest public-bank API surfaces in the country across Pix, Cobranças, Conta-Corrente, Open Finance, and Arrecadação. Merchants doing high-volume Pix and boleto operations integrate directly with BB instead of going through a PSP.
Status: alpha (0.1.0-alpha.1)
BB's Developer Portal is contract-gated — the full OpenAPI specs are visible only after merchant onboarding. Pix paths follow the BACEN Pix v2 standard; boleto, account, and statement paths are best-guesses based on BB's public marketing pages and conventions shared with peers (Itaú, Santander, Bradesco). Every unverified path is flagged TODO(verify) in src/index.ts. Pin to exact versions during 0.1.x.
Tools (13)
| Tool | Purpose |
|---|---|
create_pix_cob | Create an immediate Pix charge (cob) with QR code. |
get_pix_cob | Retrieve an immediate Pix charge by its txid. |
list_pix_cob | List immediate Pix charges (cob) by date range. |
create_pix_devolucao | Refund (devolução) a previously received Pix. |
get_pix_devolucao | Retrieve a Pix devolução by its endToEndId + refund id. |
resolve_dict_key | Resolve a DICT key (CPF, CNPJ, email, phone, EVP) to the owner's account data before sending a Pix. |
register_dict_key | Register a DICT key on a BB account owned by the merchant. |
delete_dict_key | Delete a DICT key owned by the merchant. |
register_boleto | Issue a boleto via BB Cobranças. |
get_boleto | Retrieve a boleto by nosso_numero. |
cancel_boleto | Cancel (baixa) an outstanding boleto before payment. |
get_account_balance | Retrieve the current balance of a BB conta-corrente (checking) account. |
get_statement | Retrieve account statement transactions for a BB conta-corrente over a date range. |
Install
npm install @codespar/[email protected]
Environment
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
Authentication
- OAuth2
client_credentials— token endpoint atoauth.{env}.bb.com.br. Bearer cached until ~60s before expiry. - mTLS — required by BACEN for Pix v2 in production. Sandbox typically allows TLS-only; cert/key are optional in sandbox and required in production.
gw-dev-app-key— BB API gateway key, appended as a query param on all calls.
Run
npx @codespar/mcp-banco-do-brasil
Enterprise
Need governance, budget limits, and audit trails for agent payments? CodeSpar Enterprise adds policy engine, payment routing, and compliance templates on top of these MCP servers.
License
MIT
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.