mcp-banco-do-brasil — Claude Code MCP server: Pix and boleto
Wires your agent into Banco do Brasil's API: issue Pix charges, register boletos, read balances and account statements.
claude mcp add --env BB_CLIENT_ID=<BB_CLIENT_ID> --env BB_CLIENT_SECRET=<BB_CLIENT_SECRET> --env BB_DEVELOPER_APP_KEY=<BB_DEVELOPER_APP_KEY> --env BB_CERT_PATH=<BB_CERT_PATH> --env BB_KEY_PATH=<BB_KEY_PATH> --transport stdio banco-do-brasil -- npx -y @codespar/mcp-banco-do-brasilWhat mcp-banco-do-brasil does
Thirteen tools land in your agent. Pix covers creating and fetching an immediate charge (cob), refunding a received payment (devolução), and DICT key work — looking up an owner, registering a key, removing one. Cobranças handles boleto issuance, lookup by nosso_numero, and cancellation before payment. Account tools return the balance and a statement for a date range.
Auth comes in three parts. A client_credentials OAuth2 token is fetched from oauth.{env}.bb.com.br and cached until roughly a minute before it expires. The gateway key gw-dev-app-key rides along as a query parameter on every call. BACEN wants mTLS for Pix v2 in production, so BB_CERT_PATH and BB_KEY_PATH are required there; sandbox normally accepts plain TLS and the cert stays optional.
This is alpha, 0.1.0-alpha.1. BB's developer portal hides the full OpenAPI specs behind merchant onboarding, so the boleto, account and statement paths were reconstructed from public marketing pages and conventions shared with Itaú, Santander and Bradesco. Unverified paths carry a TODO(verify) marker in src/index.ts. Pin the exact package version while 0.1.x is running — minor releases can shift behaviour.
What it helps with
- raise a Pix charge and hand the customer a QR code
- refund a received Pix by endToEndId
- check who owns a DICT key before sending money
- issue a boleto, then cancel it before payment
- pull a balance and statement for a chosen period
Example prompts for the agent
- Create a Pix charge for 250 BRL and show me the QR code
- Look up that DICT key and tell me whose account it is
- Register a boleto for this order and return the nosso_numero
How to install mcp-banco-do-brasil
Platform CLI
claude mcp add --env BB_CLIENT_ID=<BB_CLIENT_ID> --env BB_CLIENT_SECRET=<BB_CLIENT_SECRET> --env BB_DEVELOPER_APP_KEY=<BB_DEVELOPER_APP_KEY> --env BB_CERT_PATH=<BB_CERT_PATH> --env BB_KEY_PATH=<BB_KEY_PATH> --transport stdio banco-do-brasil -- npx -y @codespar/mcp-banco-do-brasilReplace <…> with your own values. 1 more environment variable is in the server README
Platform CLI
codex mcp add banco-do-brasil --env BB_CLIENT_ID=<BB_CLIENT_ID> --env BB_CLIENT_SECRET=<BB_CLIENT_SECRET> --env BB_DEVELOPER_APP_KEY=<BB_DEVELOPER_APP_KEY> --env BB_CERT_PATH=<BB_CERT_PATH> --env BB_KEY_PATH=<BB_KEY_PATH> -- npx -y @codespar/mcp-banco-do-brasilReplace <…> with your own values. 1 more environment variable is in the server README
Config file
{
"mcpServers": {
"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>"
}
}
}
}Replace <…> with your own values. 1 more environment variable is in the server README
Config file
{
"servers": {
"banco-do-brasil": {
"type": "stdio",
"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>"
}
}
}
}Replace <…> with your own values. 1 more environment variable is in the server README
Platform CLI
gemini mcp add -e BB_CLIENT_ID=<BB_CLIENT_ID> -e BB_CLIENT_SECRET=<BB_CLIENT_SECRET> -e BB_DEVELOPER_APP_KEY=<BB_DEVELOPER_APP_KEY> -e BB_CERT_PATH=<BB_CERT_PATH> -e BB_KEY_PATH=<BB_KEY_PATH> banco-do-brasil npx -y @codespar/mcp-banco-do-brasilReplace <…> with your own values. 1 more environment variable is in the server README
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about mcp-banco-do-brasil
How do I install mcp-banco-do-brasil in Claude Code?
Run `claude mcp add mcp-banco-do-brasil -e BB_CLIENT_ID=<BB_CLIENT_ID> -e BB_CLIENT_SECRET=<BB_CLIENT_SECRET> -e BB_DEVELOPER_APP_KEY=<BB_DEVELOPER_APP_KEY> -e BB_KEY_PATH=<BB_KEY_PATH> -- npx -y @codespar/mcp-banco-do-brasil`.
What does mcp-banco-do-brasil do?
It exposes Banco do Brasil's API to your agent: Pix charges and refunds, DICT keys, boletos through Cobranças, plus balance and statement reads on a conta-corrente.
What do I need for production?
An OAuth pair, BB_CLIENT_ID and BB_CLIENT_SECRET, the gateway key BB_DEVELOPER_APP_KEY, and for Pix v2 in production an mTLS certificate and key via BB_CERT_PATH and BB_KEY_PATH.
