openfinance-br-mcp
Allows interaction with Nubank accounts via Open Finance Brasil, providing tools to list accounts, get balances, transactions, credit cards, bills, PIX keys, initiate PIX, and list investments.
Provides tools to list PIX keys and initiate PIX payments with idempotency through the Open Finance Brasil APIs.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@openfinance-br-mcp what's my Nubank account balance?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
English · Português
openfinance-br-mcp
Experimental MCP server for Open Finance Brasil, with a complete mock environment and evolving FAPI-BR integration. It is not certified or validated against real institutions; see VALIDATION.md before using it outside
environment=mock.
What it is
An MCP Server that abstracts away the complexity of Open Finance Brasil (FAPI 1.0 Advanced, OAuth2, consent, mTLS) and exposes simple tools to Claude:
Claude → "how much did I spend on food in March?"
Claude uses list_transactions(bank=nubank, categorize=true, date_from=2024-03-01)
Claude → "You spent R$ 847.30 on food in March..."Related MCP server: Bradesco MCP
Supported banks
The mock environment simulates Nubank, Sicoob, Caixa, Banco do Brasil, Bradesco, Itaú, Santander, XP, PicPay, and BTG Pactual with in-memory data and no network access. These are simulations, not certified integrations.
Real adapters and the Payments API journey are experimental and unvalidated.
Payments use the v5 payments-consents/payments-pix Directory families,
dedicated per-consent tokens, verified response JWS, PAR/JAR, consent-payload
binding, and persistent idempotency.
list_pix_keys is a demonstration extension rather than a standardized Open
Finance Brasil endpoint. See VALIDATION.md
for the exact scope.
Available MCP tools
The server exposes 18 tools grouped by journey:
Accounts:
list_accounts,get_balance,list_transactionsCards:
list_credit_cards,get_credit_card_billsInvestments:
list_investments,list_funds,list_variable_incomes,list_treasure_titlesPIX:
list_pix_keys,initiate_pixData consent:
start_consent,complete_consent,check_consent_status,revoke_consentPayment consent:
start_payment_consent,complete_payment_consent,check_payment_consent_status
It also exposes the openfinance://banks/ resource, the
analyze_monthly_spending prompt, and optional URL elicitation when starting
an authorization flow.
Quick start
Prerequisites
Python 3.12 or 3.13
uv installed
# Run the published release in credential-free mock mode
uvx --from openfinance-br-mcp==0.2.0 openfinance-mcpFrom source
git clone https://github.com/brunovicco/openfinance-br-mcp.git
cd openfinance-br-mcp
# Optional: needed only for sandbox/production or DSPy categorization
cp .env.example .env
# Install dependencies
uv sync
# Run the server
uv run openfinance-mcpClaude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"openfinance-br": {
"command": "uvx",
"args": ["--from", "openfinance-br-mcp==0.2.0", "openfinance-mcp"]
}
}
}Development
# Install with dev-dependencies
uv sync
# Run the tests
uv run pytest tests/ -v
# Lint and formatting
uv run ruff check src/ tests/
uv run black src/ tests/
# Type check
uv run mypy src/Containers and Kubernetes
docker compose up openfinance-mcp
docker compose --profile test upThe k8s/ directory contains a two-replica Streamable HTTP example with
Redis-backed state. Replace every credential, signing-key, OAuth issuer,
resource-server, and domain placeholder before applying it. The server fails
closed when HTTP is exposed outside loopback without MCP client OAuth.
Architecture
Claude (MCP Client)
│ stdio or streamable-http
▼
openfinance-br-mcp (MCP Server)
├── Auth + Consent (FAPI-BR 2.2.0: private_key_jwt, PAR/JAR, PKCE, mTLS)
├── MCP Primitives (18 tools + 1 resource + 1 prompt)
│ ├── Pydantic v2 input/output schemas
│ ├── Optional URL elicitation for bank authorization
│ └── Categorizer (DSPy + Claude for transaction classification)
├── Bank Adapters (10 banks - extensible)
└── Directory Client (resolves real bank endpoints from the BCB
Directory of Participants)
│ HTTPS/mTLS
▼
Open Finance BR (BCB) - Directory of Participants
│
▼
Nubank · Sicoob · Caixa · + 100 participating institutionsEnvironment variables
Variable | Required | Description |
| ❌ |
|
| ⚠️ non-mock | Client ID registered with the institution |
| ⚠️ non-mock | RSA private key for |
| ⚠️ non-mock |
|
| ⚠️ prod | Path to the mTLS certificate |
| ⚠️ prod | mTLS private key |
| ⚠️ DSPy | Required for |
| ❌ | Shares TokenStore/ConsentManager state across replicas |
| ❌ |
|
| ⚠️ remote HTTP | Required allowlist for any non-loopback bind |
| ❌ | Enables tracing to Langfuse (with |
| ❌ | INFO, DEBUG, WARNING (default: INFO) |
| ❌ | json or console (default: json) |
See .env.example
for the full list.
Documentation
Authorization - the two token universes and why they can never cross
Contributing - dev setup, CI checks, and adding an adapter
Security - scope, disclaimer, and vulnerability reporting
Sources - specifications and RFCs followed by the implementation
Validation - what has and has not been validated
Changelog - release history
Releasing - maintainer release procedure
License
MIT
Available Tools
18 toolscheck_consent_statusARead-only
Checks the current status of a user's consent at a bank.
Args: subject_id: User's CPF or internal ID. bank: Identifier of the participating bank. ctx: MCP request context, providing access to shared dependencies.
Returns: The consent's current status.
Inputs: bank (required), subject_id (required). Returns: Result of ``check_consent_status``.
check_payment_consent_statusARead-only
Checks the current status of an exact payment consent journey.
Args: subject_id: Payer's CPF or internal ID. bank: Identifier of the participating bank. consent_id: Exact payment consent journey to query. ctx: MCP request context, providing access to shared dependencies.
Returns: The payment consent's current status.
Inputs: bank (required), consent_id (required), subject_id (required). Returns: Result of ``check_payment_consent_status``.
complete_consentA
Completes a consent flow using the URL the bank redirected the user to after they finished logging in and authorizing.
Because FAPI-BR mandates response_mode=fragment, that URL's parameters live after a '#', not a '?' - copy the complete address bar contents after being redirected, not just the query string.
Args: callback_url: The full URL the user's browser landed on after authorizing (or denying) consent at the bank. ctx: MCP request context, providing access to shared dependencies.
Returns: The final consent status after completing the exchange.
Inputs: callback_url (required). Returns: Result of ``complete_consent``.
complete_payment_consentA
Completes a payment consent flow using the URL the bank redirected the user to after authorizing (or denying) the payment.
Args: callback_url: The full URL the user's browser landed on after authorizing (or denying) the payment consent at the bank. ctx: MCP request context, providing access to shared dependencies.
Returns: The final payment consent status after completing the exchange.
Inputs: callback_url (required). Returns: Result of ``complete_payment_consent``.
get_balanceARead-only
Returns the available, blocked, and automatically invested balance of a specific bank account on Open Finance Brasil.
Args: subject_id: User's CPF. bank: Identifier of the participating bank. account_id: Account ID returned by list_accounts. ctx: MCP request context, providing access to shared adapters.
Returns: The account's current balance.
Inputs: bank (required), account_id (required), subject_id (required). Returns: Result of ``get_balance``.
get_credit_card_billsARead-only
Returns the bills (open and past) of a credit card via Open Finance Brasil, including total amount, minimum payment, and due date.
Args: subject_id: User's CPF. bank: Identifier of the participating bank. credit_card_account_id: ID returned by list_credit_cards. ctx: MCP request context, providing access to shared adapters.
Returns: The bills of the given credit card account.
Inputs: bank (required), subject_id (required), credit_card_account_id (required). Returns: Result of ``get_credit_card_bills``.
initiate_pixADestructiveIdempotent
Initiates a PIX payment via Open Finance Brasil. Requires an active payment consent. The idempotency_key field prevents duplicate charges on retries.
Outside environment='mock', requires an AUTHORISED payment
consent for this subject/bank, obtained beforehand via
start_payment_consent + complete_payment_consent
(tools/payments.py) - a data-sharing consent alone is not
sufficient. In mock mode this check is skipped entirely, since the
mock adapter has no payment-consent resource to check against.
Args:
subject_id: Payer's CPF.
bank: Identifier of the participating bank.
amount: Canonical amount in BRL (e.g. "150.00").
creditor_key: PIX key of the recipient.
creditor_key_type: Type of the recipient's key.
debtor_account_id: ID of the account to debit, returned by
list_accounts.
idempotency_key: Client-generated UUID to prevent duplicates.
ctx: MCP request context, providing access to shared adapters
and the persistent idempotency store.
description: Payment description/reason (max 140 chars).
consent_id: Payment consent returned by
start_payment_consent. Required outside mock mode.
Returns: Status of the initiated (or previously cached) payment.
Inputs: bank (required), amount (required), subject_id (required), creditor_key (required), +5 more. Returns: Result of ``initiate_pix``.
list_accountsARead-only
Lists all bank accounts (checking, savings, prepaid) of a user at an institution participating in Open Finance Brasil.
Args: subject_id: User's CPF (digits only) or internal ID. bank: Identifier of the participating bank. ctx: MCP request context, providing access to shared adapters.
Returns: The user's accounts at the given bank.
Inputs: bank (required), subject_id (required). Returns: Result of ``list_accounts``.
list_credit_cardsARead-only
Lists all credit card accounts of a user at an institution participating in Open Finance Brasil, including available and total credit limit.
Args: subject_id: User's CPF. bank: Identifier of the participating bank. ctx: MCP request context, providing access to shared adapters.
Returns: The user's credit card accounts at the given bank.
Inputs: bank (required), subject_id (required). Returns: Result of ``list_credit_cards``.
list_fundsARead-only
Lists a user's investment fund positions via Open Finance Brasil Fase 4 (P1.3), including quota quantity/price and gross/net amount.
Args: subject_id: User's CPF. bank: Participating bank. ctx: MCP request context, providing access to shared adapters.
Returns: The user's investment funds and aggregate totals.
Inputs: bank (required), subject_id (required). Returns: Result of ``list_funds``.
list_investmentsARead-only
Lists a user's bank fixed-income investments (CDB, LCI, LCA, RDB) via Open Finance Brasil Fase 4, including gross amount, net amount, contracted rate, and indexer.
Args: subject_id: User's CPF. bank: Participating bank. ctx: MCP request context, providing access to shared adapters.
Returns: The user's fixed-income investments and aggregate totals.
Inputs: bank (required), subject_id (required). Returns: Result of ``list_investments``.
list_pix_keysARead-only
Lists the PIX keys (CPF, email, phone, EVP) registered to a bank account via Open Finance Brasil.
Only available in environment='mock' - see module docstring.
Args: subject_id: User's CPF. bank: Identifier of the participating bank. account_id: Account ID. ctx: MCP request context, providing access to shared adapters.
Returns: The PIX keys registered to the given account.
Inputs: bank (required), account_id (required), subject_id (required). Returns: Result of ``list_pix_keys``.
list_transactionsARead-only
Returns the bank statement of an account on Open Finance Brasil with date and type filters. Supports automatic transaction categorization via AI (categorize=true, requires ANTHROPIC_API_KEY).
Args: subject_id: User's CPF. bank: Identifier of the participating bank. account_id: Account ID returned by list_accounts. ctx: MCP request context, providing access to shared adapters and the categorizer. date_from: Start date of the period. date_to: End date of the period. credit_debit_type: Restrict to credits or debits only. page: Page number (1-based). page_size: Records per page (1-1000). categorize: If true, categorizes each transaction via AI.
Returns: The account's transactions for the requested period.
Inputs: bank (required), account_id (required), subject_id (required), page, +5 more. Returns: Result of ``list_transactions``.
list_treasure_titlesARead-only
Lists a user's treasury bond (Tesouro Direto) positions via Open Finance Brasil Fase 4 (P1.3), including quantity, updated unit price, and gross/net amount.
Args: subject_id: User's CPF. bank: Participating bank. ctx: MCP request context, providing access to shared adapters.
Returns: The user's treasury bonds and aggregate totals.
Inputs: bank (required), subject_id (required). Returns: Result of ``list_treasure_titles``.
list_variable_incomesARead-only
Lists a user's variable income asset positions (stocks, ETFs, and other exchange-traded assets) via Open Finance Brasil Fase 4 (P1.3), including quantity, closing price, and gross amount.
No net_amount is returned here (unlike list_investments/list_funds/ list_treasure_titles): the real Variable Incomes spec's balance data only publishes a gross amount - taxes/fees on these assets are reported per-transaction (broker notes), not as a running net position.
Args: subject_id: User's CPF. bank: Participating bank. ctx: MCP request context, providing access to shared adapters.
Returns: The user's variable income assets and an aggregate gross total.
Inputs: bank (required), subject_id (required). Returns: Result of ``list_variable_incomes``.
revoke_consentADestructiveIdempotent
Revokes a user's consent at a bank and forgets the local token.
Args: subject_id: User's CPF or internal ID. bank: Identifier of the participating bank. ctx: MCP request context, providing access to shared dependencies.
Returns: Confirmation that the consent was revoked.
Inputs: bank (required), subject_id (required). Returns: Result of ``revoke_consent``.
start_consentA
Starts the Open Finance Brasil consent flow for a user at a bank.
Creates a consent resource at the bank, then builds a FAPI-BR
compliant (PAR + JAR) authorization URL. The user must open this
URL in a browser, log in, and authorize the requested scopes at
the bank. Once redirected back, call complete_consent with the
resulting URL to finish the flow.
Args: subject_id: User's CPF (digits only) or internal ID. bank: Identifier of the participating bank. scopes: Desired data-sharing scopes, e.g. ['accounts', 'balances', 'transactions', 'overdraft_limits', 'credit_card_accounts', 'credit_card_limits', 'credit_card_bills', 'credit_card_transactions', 'bank_fixed_incomes', 'funds', 'variable_incomes', 'treasure_titles']. Does NOT include 'pix'/payments - payment initiation uses a separate, dedicated payment consent (Payments API), not this data-sharing consent; see tools/pix.py. ctx: MCP request context, providing access to shared dependencies. request_url_elicitation: Ask a compatible MCP client to open the bank authorization URL using URL-mode elicitation. The URL is always returned as well, so clients without elicitation support can continue with the existing copy-and-open flow.
Returns: The consent ID and the URL the user must open to authorize it.
Inputs: bank (required), scopes (required), subject_id (required), request_url_elicitation. Returns: Result of ``start_consent``.
start_payment_consentA
Starts the Open Finance Brasil Payments API consent flow for one specific PIX payment.
Creates a payment consent describing exactly this payment, then
builds a FAPI-BR compliant (PAR + JAR) authorization URL. The user
must open this URL, log in, and authorize this specific payment at
the bank. Once redirected back, call complete_payment_consent
with the resulting URL, then initiate_pix to actually create
the payment.
Args: subject_id: Payer's CPF (digits only) or internal ID. bank: Identifier of the participating bank. amount: Payment amount in BRL (e.g. '150.00'). creditor_key: PIX key of the recipient. creditor_key_type: Type of the recipient's key. debtor_account_id: ID of the account to debit. ctx: MCP request context, providing access to shared dependencies. description: Payment description/reason (max 140 chars). request_url_elicitation: Ask a compatible MCP client to open the bank authorization URL using URL-mode elicitation. The URL is still returned for clients that use the manual flow.
Returns: The payment consent ID and the URL the user must open to authorize it.
Inputs: bank (required), amount (required), subject_id (required), creditor_key (required), +4 more. Returns: Result of ``start_payment_consent``.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 18 tools
Every tool targets a distinct resource or lifecycle step. list_* tools clearly separate accounts, credit cards, Pix keys, and each investment type; consent tools have explicit data vs payment distinction. No two tools appear to perform the same operation.
Names follow a consistent verb_noun pattern: list_ for collections, get_ for single items, start_/complete_/check_ for consent flows. Minor deviation: get_credit_card_bills returns a collection rather than a singular item, but this is a small and understandable exception.
18 tools is slightly above the ideal 3-15 range but justified by the breadth of Open Finance Brasil (accounts, cards, PIX, investments, consent flows). Each tool addresses a meaningful use case without redundancy.
The tool surface covers core account, payment, and investment workflows, plus the required consent lifecycles. Obvious gap: credit_card_transactions scope is offered in consent but no tool retrieves credit card transactions; also no revoke_payment_consent, though less critical.
Maintenance
Related MCP Connectors
Brazilian Open Finance MCP — 30+ banks (Itaú, Nubank, etc.) to Claude/Cursor. Read-only.
Brazilian personal & business finance with Open Finance: transactions, cards, investments.
Open Finance API and MCP discovery for developers and AI agents building in Brazil.
Ask your AI about Brazilian bank spending. Read-only bank access, never moves money. Paid plan.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceConnects Brazilian banks (Itaú, Bradesco, Nubank, etc.) to AI agents, enabling natural language queries about expenses, statements, investments, and credit cards via regulated Open Finance.27MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to query Bradesco bank accounts via Open Finance Brazil, providing read-only access to balances, statements, credit card bills, and investments.MIT
- AlicenseNot gradedqualityCmaintenanceConnects Claude, ChatGPT, and other AI agents to Caixa Econômica Federal accounts via Open Finance Brasil, enabling natural language queries about balances, transactions, credit card bills, and investments in read-only mode.MIT
- AlicenseNot gradedqualityCmaintenanceConnects Nubank accounts to Claude, ChatGPT, and AI agents via Open Finance Brasil, enabling natural language queries about balances, statements, credit card bills, and investments in read-only mode.MIT