English Français العربية

io.github.brunovicco/openfinance-br-mcp

Official registry Finance and payments

Secure Open Finance Brasil MCP server with typed tools and a credential-free mock mode

Source code Documentation

What can you do with io.github.brunovicco/openfinance-br-mcp?

  • Accounts: list_accounts, get_balance, list_transactions
  • Cards: list_credit_cards, get_credit_card_bills
  • Investments: list_investments, list_funds,
  • PIX: list_pix_keys, initiate_pix
  • Data consent: start_consent, complete_consent,
  • Payment consent: start_payment_consent, complete_payment_consent,

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

PYPI package openfinance-br-mcp
Claude Code 
claude mcp add openfinance-br-mcp -e 'ENVIRONMENT=mock' -e 'CLIENT_ID=<CLIENT_ID>' -e 'PRIVATE_KEY_PATH=<PRIVATE_KEY_PATH>' -e 'PRIVATE_KEY_KID=<PRIVATE_KEY_KID>' -e 'MTLS_CERT_PATH=<MTLS_CERT_PATH>' -e 'MTLS_KEY_PATH=<MTLS_KEY_PATH>' -e 'REDIS_URL=<your redis_url>' -e 'ANTHROPIC_API_KEY=<your anthropic_api_key>' -- uvx openfinance-br-mcp==0.2.0
JSON configuration (Claude Desktop, Cursor, VS Code) 
{
    "mcpServers": {
        "openfinance-br-mcp": {
            "command": "uvx",
            "args": [
                "openfinance-br-mcp==0.2.0"
            ],
            "env": {
                "ENVIRONMENT": "mock",
                "CLIENT_ID": "<CLIENT_ID>",
                "PRIVATE_KEY_PATH": "<PRIVATE_KEY_PATH>",
                "PRIVATE_KEY_KID": "<PRIVATE_KEY_KID>",
                "MTLS_CERT_PATH": "<MTLS_CERT_PATH>",
                "MTLS_KEY_PATH": "<MTLS_KEY_PATH>",
                "REDIS_URL": "<your redis_url>",
                "ANTHROPIC_API_KEY": "<your anthropic_api_key>"
            }
        }
    }
}

Environment variables

  • ENVIRONMENT 'mock' (default, no credentials needed - runs entirely in-memory), 'sandbox', or 'production'
  • CLIENT_ID Client ID registered with the participating institution. Required unless ENVIRONMENT=mock
  • PRIVATE_KEY_PATH Path to the RSA private key used for private_key_jwt and JAR signing outside mock mode
  • PRIVATE_KEY_KID Key ID matching the registered client JWKS entry outside mock mode
  • MTLS_CERT_PATH Path to the client mTLS certificate used outside mock mode
  • MTLS_KEY_PATH Path to the client mTLS private key used outside mock mode
  • REDIS_URL secret Optional Redis connection URL for persistent consent and token state
  • ANTHROPIC_API_KEY secret Required only when calling list_transactions with categorize=true (DSPy transaction categorization)

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents
  1. openfinance-br-mcp
  2. What it is
  3. Supported banks
  4. Available MCP tools
  5. Quick start
  6. Development
  7. Containers and Kubernetes
  8. Architecture
  9. Environment variables
  10. Documentation
  11. License

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..."

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

VariableRequiredDescription
ENVIRONMENT❌mock (default, no credentials needed), sandbox, or production
CLIENT_ID⚠️ non-mockClient ID registered with the institution
PRIVATE_KEY_PATH⚠️ non-mockRSA private key for private_key_jwt/JAR signing
PRIVATE_KEY_KID⚠️ non-mockkid matching the registered client JWKS
MTLS_CERT_PATH⚠️ prodPath to the mTLS certificate
MTLS_KEY_PATH⚠️ prodmTLS private key
ANTHROPIC_API_KEY⚠️ DSPyRequired for categorize=true
REDIS_URL❌Shares TokenStore/ConsentManager state across replicas
MCP_TRANSPORT❌stdio (default) or streamable-http
MCP_HTTP_ALLOWED_ORIGINS⚠️ remote HTTPRequired 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

Frequently asked questions

What is io.github.brunovicco/openfinance-br-mcp?

Secure Open Finance Brasil MCP server with typed tools and a credential-free mock mode

How do I install io.github.brunovicco/openfinance-br-mcp?

It runs on your machine. In Claude Code: claude mcp add openfinance-br-mcp -e 'ENVIRONMENT=mock' -e 'CLIENT_ID=<CLIENT_ID>' -e 'PRIVATE_KEY_PATH=<PRIVATE_KEY_PATH>' -e 'PRIVATE_KEY_KID=<PRIVATE_KEY_KID>' -e 'MTLS_CERT_PATH=<MTLS_CERT_PATH>' -e 'MTLS_KEY_PATH=<MTLS_KEY_PATH>' -e 'REDIS_URL=<your redis_url>' -e 'ANTHROPIC_API_KEY=<your anthropic_api_key>' -- uvx openfinance-br-mcp==0.2.0. For other clients, paste the JSON configuration from this page into their MCP settings.

Does io.github.brunovicco/openfinance-br-mcp need an API key?

Yes. It expects REDIS_URL, ANTHROPIC_API_KEY, which you set in its configuration.

Is io.github.brunovicco/openfinance-br-mcp open source?

Yes. Its code is on GitHub under the MIT license.

Who maintains io.github.brunovicco/openfinance-br-mcp?

It is published by brunovicco. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.