mcp-bradesco

@codespar/mcp-bradesco

MCP server for Bradesco — Brazil's 2nd largest private bank (after Itaú).

Together with @codespar/mcp-itau, @codespar/mcp-banco-inter, and @codespar/mcp-stark-bank, this covers the major BR private-bank API landscape. Merchants with meaningful Pix, boleto, and cash-management volume integrate directly with Bradesco instead of going through a PSP.

Status: alpha (0.1.0-alpha.1)

Bradesco's Developer Portal is contract-gated — the full OpenAPI specs for Pix, Cobrança, Arrecadação, and Extrato are only visible to onboarded merchants. The endpoint paths in this server are best-guesses based on (a) BACEN Pix v2 standard paths, (b) Bradesco's public integration guides, and (c) conventions shared across Itaú / Santander / BB. Every unverified path is flagged TODO(verify) in the source.

Pin to exact versions during 0.1.x; paths will be corrected to match the portal spec once an onboarded merchant can validate.

Tools (22)

Tool	Purpose
get_oauth_token	Mint or return a cached OAuth2 client_credentials bearer token for the Bradesco Developer Portal.
send_pix	Initiate an outbound Pix payment from the merchant's Bradesco account.
create_pix_qr	Create a dynamic Pix charge with QR code (cob).
get_pix	Retrieve a Pix transaction by its BCB endToEndId (E).
resolve_dict_key	Resolve a DICT key (CPF, CNPJ, email, phone, EVP) to the owner's account data before sending a Pix.
refund_pix	Refund (devolução) a previously received Pix.
create_boleto	Issue a boleto via Bradesco Cobrança.
get_boleto	Retrieve a boleto by its Bradesco identifier (id or nosso_numero).
cancel_boleto	Cancel (baixa) an outstanding boleto before payment.
get_statement	Retrieve account statement transactions for a given period.
arrecadacao_pay	Pay a utility, tax, or concessionária bill via Bradesco Arrecadação.
list_pix_received	List Pix transactions received by the merchant during a period.
create_pix_due_charge	Create a Pix charge with a due date (cobv) — commonly used for installments and scheduled invoices.
get_pix_due_charge	Retrieve a Pix due charge (cobv) by txid.
update_pix_due_charge	Patch a Pix due charge (cobv) — revise amount, due date, discount, or debtor before payment.
register_dict_key	Register a DICT key (CPF, CNPJ, email, phone, or EVP) pointing to a merchant account at Bradesco.
delete_dict_key	Delete (unlink) a DICT key that points to a merchant account at Bradesco.
list_boletos	List boletos issued by the merchant filtered by status and issue/due period.
get_boleto_pdf	Download the boleto PDF as base64.
get_account_balance	Retrieve the current available balance (saldo disponível) for a merchant account.
transfer_ted	Execute a TED (or TEF when intra-Bradesco) transfer from the merchant's account to a beneficiary bank account.
pay_tax_darf	Pay a federal tax (DARF) or union fee (GRU) via Bradesco Arrecadação.

Install

npm install @codespar/[email protected]

Environment

BRADESCO_CLIENT_ID="..."       # OAuth client_id from Bradesco's Developer Portal
BRADESCO_CLIENT_SECRET="..."   # OAuth client_secret
BRADESCO_CERT_PATH="/abs/path/to/client.crt"   # mTLS client certificate
BRADESCO_KEY_PATH="/abs/path/to/client.key"    # mTLS private key
BRADESCO_ENV="sandbox"                          # or "production" (default: sandbox)

Authentication

Two factors are both required on every call:

1. OAuth2 client_credentials — the server calls the token endpoint, caches the bearer until ~60s before expiry, and attaches Authorization: Bearer <token> to downstream calls.
2. mTLS — BACEN mandates mutual TLS for Pix v2, and Bradesco enforces it across product families. The server loads the client certificate and private key from the paths you set, builds a Node https.Agent, and routes every request through it.

You obtain the cert + key bundle from the Bradesco Developer Portal after your merchant contract is signed. They are distinct from the OAuth credentials.

Base URLs

• Production: https://proxy.api.prebanco.com.br (Bradesco's standard external proxy)
• Sandbox: https://apihom-bradescorip.bradesco.com.br (homologação)

Both hosts are marked TODO(verify) — Bradesco provisions per-merchant subdomains in some product families and the exact homologação host may differ. Fork and override BASE_URL if your portal provisioning differs.

Run

# stdio (default)
npx @codespar/mcp-bradesco

# HTTP transport
MCP_HTTP=true MCP_PORT=3000 npx @codespar/mcp-bradesco

Caveats

• Paths are unverified. See the TODO(verify) markers in src/index.ts. Onboarded merchants should validate against their portal-issued OpenAPI spec and open a PR.
• Base URLs are best-guess. See above — override if your provisioning differs.
• Arrecadação barcode validation is server-side in this alpha — no client-side mod-10 / mod-11 check yet.

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