io.github.codespar/mcp-itau — MCP Server for Itaú Unibanco

This MCP server provides Model Context Protocol access to Itaú Unibanco capabilities in Brazil, covering Pix, Cobrança (boleto), Arrecadação, and Extrato. Extrato integration uses OAuth2 plus mTLS. The server is described as an alpha release (0.1.0-alpha.1) with endpoint paths based on documented standards and best guesses.

🛠️ Key Features

Pix
Cobrança (boleto)
Arrecadação
Extrato (OAuth2 + mTLS)
Alpha status: 0.1.0-alpha.1

🚀 Use Cases

Merchant integrations for high-volume Pix, boleto, and cash-management workloads
Direct integration with Itaú API surface instead of going through a PSP
Access to bank-related data via Extrato using OAuth2 + mTLS

⚡ Developer Benefits

MCP tooling for agentic-commerce and LLM tools workflows
Focus on Brazil and fintech payment domains (Pix, payments, open finance)

⚠️ Limitations

Itaú Developer Portal is contract-gated; full OpenAPI specs for these services are only visible to onboarded merchants
Endpoint paths are best-guesses based on BACEN Pix v2 standard paths and partial information

Status: alpha (0.1.0-alpha.1)

Itaú'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) Itaú's public marketing pages, and (c) conventions shared across Santander / Bradesco / 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 Itaú Developer Portal.

send_pix

Initiate an outbound Pix payment from the merchant's Itaú 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 Itaú Cobrança.

get_boleto

Retrieve a boleto by its Itaú 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 Itaú Arrecadação.

create_pix_cobv

Create a Pix charge with due date (cobv) — used for boleto-like Pix where the payer can pay at or after a d...

list_pix_charges

List immediate Pix charges (cob) registered by the merchant within a date range.

register_pix_key

delete_pix_key

Delete a DICT key owned by the merchant.

list_pix_keys

List DICT keys currently registered to the merchant's Itaú accounts.

get_boleto_pdf

Download the PDF of an issued boleto.

send_ted

Send a TED transfer to an account at another bank.

transfer_between_accounts

TAA — transfer between two Itaú accounts (owned by the merchant or a counterparty).

get_tariffs

Query the tariff schedule applicable to the merchant's active contracts (Pix per-transaction, boleto regist...

list_dda_bills

List bills registered for the merchant under the DDA (Débito Direto Autorizado) enrolment.

schedule_payment

Schedule a future-dated payment (Pix, boleto, arrecadação, or TED).

Environment

bash

ITAU_CLIENT_ID="..."       # OAuth client_id from Itaú's Developer Portal
ITAU_CLIENT_SECRET="..."   # OAuth client_secret
ITAU_CERT_PATH="/abs/path/to/client.crt"   # mTLS client certificate
ITAU_KEY_PATH="/abs/path/to/client.key"    # mTLS private key
ITAU_ENV="sandbox"                          # or "production" (default: sandbox)

Authentication

Two factors are both required on every call:

OAuth2 client_credentials — the server calls the token endpoint, caches the bearer until ~60s before expiry, and attaches Authorization: Bearer <token> to downstream calls.

mTLS — BACEN mandates mutual TLS for Pix v2, and Itaú 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 Itaú Developer Portal after your merchant contract is signed. They are distinct from the OAuth credentials.

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.

Sandbox host is a guess. Itaú issues a sandbox subdomain per merchant; override by editing BASE_URL if your provisioned sandbox URL differs.

Arrecadação barcode validation is server-side in this alpha — no client-side mod-10 / mod-11 check yet.

Install

Configuration

Environment variables

ITAU_CLIENT_IDrequired

Itaú OAuth client_id issued via the Developer Portal after contract onboarding.

ITAU_CLIENT_SECRETrequiredsecret

Itaú OAuth client_secret.

ITAU_CERT_PATHrequired

Absolute path to the mTLS client certificate (.crt or .pem). BACEN mandates mTLS for Pix v2.

ITAU_KEY_PATHrequiredsecret

Absolute path to the mTLS private key (.key or .pem).

ITAU_ENV

Environment: 'sandbox' or 'production'. Defaults to 'sandbox'.

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "mcp-itau": {
      "command": "npx",
      "args": [
        "-y",
        "@codespar/mcp-itau@0.2.0-alpha.3"
      ],
      "env": {
        "ITAU_CLIENT_ID": "<YOUR_ITAU_CLIENT_ID>",
        "ITAU_CLIENT_SECRET": "<YOUR_ITAU_CLIENT_SECRET>",
        "ITAU_CERT_PATH": "<YOUR_ITAU_CERT_PATH>",
        "ITAU_KEY_PATH": "<YOUR_ITAU_KEY_PATH>",
        "ITAU_ENV": "<YOUR_ITAU_ENV>"
      }
    }
  }
}

io.github.codespar/mcp-itau