English Français العربية

io.github.brunovicco/openfinance-br-mcp

Registre officiel Finance et paiements

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

Code source Documentation

Que pouvez-vous faire avec 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,

Installation

Ajoutez ceci à la configuration MCP de votre client (Claude Desktop : claude_desktop_config.json ; Cursor : .cursor/mcp.json ; VS Code et les autres utilisent la même forme « mcpServers »).

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
Configuration JSON (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>"
            }
        }
    }
}

Variables d'environnement

  • 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

Tirée du README du projet sur GitHub, actualisée chaque semaine. Les liens ouvrent GitHub.

Sommaire
  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

Questions fréquentes

Qu'est-ce que io.github.brunovicco/openfinance-br-mcp ?

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

Comment installer io.github.brunovicco/openfinance-br-mcp ?

Il s'exécute sur votre machine. Dans 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. Pour les autres clients, collez la configuration JSON de cette page dans leurs réglages MCP.

Faut-il une clé API pour io.github.brunovicco/openfinance-br-mcp ?

Oui. Il attend REDIS_URL, ANTHROPIC_API_KEY, à renseigner dans sa configuration.

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

Oui. Son code est sur GitHub sous licence MIT.

Qui maintient io.github.brunovicco/openfinance-br-mcp ?

Il est publié par brunovicco. AI.tn le référence sans le maintenir ni le recommander.

Issu du registre MCP officiel. Être listé n'est pas une recommandation : vérifiez le code et les permissions d'un serveur avant de lui donner accès à vos données.