# mcp-banco-do-brasil

Wires your agent into Banco do Brasil's API: issue Pix charges, register boletos, read balances and account statements.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 274
- Author: codespar
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/codespar/mcp-dev-latam/tree/HEAD/packages/banking/banco-do-brasil
- Updated: 2026-09-27
- HTML: https://affpapa.org/en/nevibecode/mcp/mcp-banco-do-brasil

## What it 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.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `BB_CLIENT_ID`, `BB_CLIENT_SECRET`, `BB_DEVELOPER_APP_KEY`, `BB_CERT_PATH`, `BB_KEY_PATH`, `BB_ENV` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
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-brasil
```
Replace <…> with your own values. 1 more environment variable is in the server README

### Codex

**Platform CLI**
```bash
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-brasil
```
Replace <…> with your own values. 1 more environment variable is in the server README

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "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

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "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

### Gemini CLI

**Platform CLI**
```bash
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-brasil
```
Replace <…> with your own values. 1 more environment variable is in the server README

## When to use it
- 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
- 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

## Similar
- [MCP Toolbox for Databases](https://affpapa.org/en/nevibecode/mcp/googleapis-mcp-toolbox-for-databases.md) — MCP server · ★ 16717
- [PostHog MCP Server](https://affpapa.org/en/nevibecode/mcp/posthog-mcp-server.md) — MCP server · ★ 40409
- [OpenWork MCP Gateway](https://affpapa.org/en/nevibecode/mcp/openwork-mcp-gateway.md) — MCP server · ★ 24242
- [Keploy](https://affpapa.org/en/nevibecode/mcp/keploy.md) — MCP server · ★ 18727
- [Nhost](https://affpapa.org/en/nevibecode/mcp/nhost.md) — MCP server · ★ 9366
- [basebalance.cloud — x402 RPC & MCP gateway](https://affpapa.org/en/nevibecode/mcp/basebalancecloud-x402-rpc-mcp-gateway.md) — MCP server · ★ 7506

From the same set: [codespar/mcp-dev-latam](https://affpapa.org/en/nevibecode/by/codespar/mcp-dev-latam.md) — 124 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md