English Français العربية

io.github.brunovicco/openfinance-br-mcp

السجل الرسمي المالية والمدفوعات

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

الشيفرة المصدرية التوثيق

ماذا يمكنك أن تفعل مع 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,

التثبيت

أضف هذا إلى إعدادات MCP في عميلك (Claude Desktop: claude_desktop_config.json، وCursor: ‏.cursor/mcp.json، ويستخدم VS Code وغيره الصيغة نفسها «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
إعداد 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>"
            }
        }
    }
}

متغيرات البيئة

  • 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 سري Optional Redis connection URL for persistent consent and token state
  • ANTHROPIC_API_KEY سري Required only when calling list_transactions with categorize=true (DSPy transaction categorization)

التوثيق

مأخوذ من ملف README للمشروع على GitHub ويُحدَّث أسبوعيًا. تفتح الروابط على GitHub.

المحتويات
  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

الأسئلة الشائعة

ما هو io.github.brunovicco/openfinance-br-mcp؟

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

كيف أثبّت io.github.brunovicco/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 من هذه الصفحة في إعدادات MCP الخاصة بهم.

هل يحتاج io.github.brunovicco/openfinance-br-mcp إلى مفتاح API؟

نعم. يتطلب REDIS_URL, ANTHROPIC_API_KEY، وتضبطها في إعداداته.

هل io.github.brunovicco/openfinance-br-mcp مفتوح المصدر؟

نعم. شيفرته متاحة على GitHub بترخيص MIT.

من يصون io.github.brunovicco/openfinance-br-mcp؟

ينشره brunovicco. يدرجه AI.tn لكنه لا يصونه ولا يوصي به.

من سجل MCP الرسمي. الإدراج ليس توصية: راجع شيفرة الخادم وصلاحياته قبل منحه الوصول إلى بياناتك.