Skip to main content
Glama
openfinance-br-mcp

openfinance-br-mcp

by brunovicco

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.

Python 3.12 uv Code style: black Ruff


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_transactions

  • Cards: list_credit_cards, get_credit_card_bills

  • Investments: list_investments, list_funds, list_variable_incomes, list_treasure_titles

  • PIX: list_pix_keys, initiate_pix

  • Data consent: start_consent, complete_consent, check_consent_status, revoke_consent

  • Payment 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-mcp

From 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-mcp

Claude 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 up

The 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 institutions

Environment variables

Variable

Required

Description

ENVIRONMENT

❌

mock (default, no credentials needed), sandbox, or production

CLIENT_ID

⚠️ non-mock

Client ID registered with the institution

PRIVATE_KEY_PATH

⚠️ non-mock

RSA private key for private_key_jwt/JAR signing

PRIVATE_KEY_KID

⚠️ non-mock

kid matching the registered client JWKS

MTLS_CERT_PATH

⚠️ prod

Path to the mTLS certificate

MTLS_KEY_PATH

⚠️ prod

mTLS private key

ANTHROPIC_API_KEY

⚠️ DSPy

Required for categorize=true

REDIS_URL

❌

Shares TokenStore/ConsentManager state across replicas

MCP_TRANSPORT

❌

stdio (default) or streamable-http

MCP_HTTP_ALLOWED_ORIGINS

⚠️ remote HTTP

Required allowlist for any non-loopback bind

LANGFUSE_OTLP_ENDPOINT

❌

Enables tracing to Langfuse (with LANGFUSE_PUBLIC_KEY/LANGFUSE_SECRET_KEY)

LOG_LEVEL

❌

INFO, DEBUG, WARNING (default: INFO)

LOG_FORMAT

❌

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 tools
get_balanceA
Read-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_billsA
Read-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_pixA
DestructiveIdempotent

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_accountsA
Read-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_cardsA
Read-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_fundsA
Read-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_investmentsA
Read-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_keysA
Read-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_transactionsA
Read-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_titlesA
Read-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_incomesA
Read-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``.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 18 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Connects Brazilian banks (Itaú, Bradesco, Nubank, etc.) to AI agents, enabling natural language queries about expenses, statements, investments, and credit cards via regulated Open Finance.
      27
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to query Bradesco bank accounts via Open Finance Brazil, providing read-only access to balances, statements, credit card bills, and investments.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Connects 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
    • A
      license
      Not graded
      quality
      C
      maintenance
      Connects 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