English · Português

openfinance-br-mcp

Experimental MCP server for Open Finance Brasil, with a complete mock environment and an evolving implementation toward FAPI-BR integration. Not certified, and not yet validated against real institutions - see VALIDATION.md and the implementation plan in IMPLEMENTATION_PLAN.md before relying on this 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

Mock adapters are implemented for the ten institutions below - each returns realistic, in-memory sample data with zero credentials or network access, and is the primary way to explore this project today. Real (non-mock) support is experimental: it has not been exercised against any bank's actual sandbox or production environment, is not FAPI-BR certified, and several endpoints/paths are still being brought in line with the official OpenAPI specs (tracked in IMPLEMENTATION_PLAN.md).

PIX payment initiation (initiate_pix) and list_pix_keys are currently restricted to environment=mock, the real Open Finance Brasil Payments API journey (dedicated payment consent, signed JWS requests/responses, persistent idempotency) is not yet implemented; see IMPLEMENTATION_PLAN.md, phase P2.

New banks: implement BankAdapter (or subclass DefaultOpenFinanceAdapter) and register it - see "Adding a new bank" below.

Available MCP tools

Quick start

Prerequisites

• Python 3.12+
• uv installed

# Clone the repository
git clone https://github.com/brunovicco/openfinance-br-mcp.git
cd openfinance-br-mcp

# Configure the environment
cp .env.example .env
# Edit .env with your CLIENT_ID, CLIENT_SECRET, etc.

# 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": "uv",
      "args": ["run", "--directory", "/path/to/openfinance-br-mcp", "openfinance-mcp"],
      "env": {
        "CLIENT_ID": "your_client_id",
        "CLIENT_SECRET": "your_client_secret",
        "MTLS_ENABLED": "false"
      }
    }
  }
}

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/

Docker

# Build
docker build -t openfinance-br-mcp .

# Run the tests
docker compose --profile test up

# Run the server
docker compose up openfinance-mcp

Kubernetes

# Create the namespace
kubectl create namespace fintech

# Apply the configuration (edit the secrets first!)
kubectl apply -f k8s/config-and-secrets.yaml
kubectl apply -f k8s/deployment.yaml
kubectl apply -f k8s/service.yaml
kubectl apply -f k8s/ingress.yaml

Runs streamable-http behind 2 replicas, with CLIENT_ID/CLIENT_SECRET/ ANTHROPIC_API_KEY mounted as secret files rather than env vars, and a shared Redis backend (REDIS_URL) so token/consent state is visible across replicas.

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 Tools       (12 tools, input validated with Pydantic v2)
  │   └── 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

Design principles

• SOLID: BankAdapter ABC (O/C, LSP), single-responsibility tools, constructor-based DI
• 12-Factor: config via env, stateless, logs to stdout
• Security: mTLS, SecretStr, in-memory tokens, mandatory PKCE
• Idempotency: asyncio.Lock on token refresh, X-Idempotency-Key on PIX
• DSPy: transaction categorization framed as an LLM classification problem

Environment variables

See .env.example for the full list.

Adding a new bank

1. Create src/openfinance_br_mcp/adapters/my_bank.py
2. Inherit from DefaultOpenFinanceAdapter (or BankAdapter directly for a fully custom implementation)
3. Override bank_id, and pass base_url/token_endpoint defaults
4. Add its ISPB to directory/client.py's _ISPB_BY_BANK and register the adapter class in context.py

Documentation

• docs/en/authorization.md - the two token universes (MCP client auth vs. FAPI-BR bank auth), and why they can never cross
• CONTRIBUTING.md - dev setup, CI checks, adding a bank adapter
• SECURITY.md - scope, disclaimer, and how to report a vulnerability
• SOURCES.md - specs and RFCs this implementation follows
• VALIDATION.md - what's actually been validated, and what hasn't (no real BCB sandbox run)
• CHANGELOG.md - release history

License

MIT