{
  "markdown": "**English** · [Português](https://github.com/brunovicco/openfinance-br-mcp/blob/main/README.pt-BR.md)\n\n<!-- mcp-name: io.github.brunovicco/openfinance-br-mcp -->\n\n# openfinance-br-mcp\n\n> Experimental MCP server for **Open Finance Brasil**, with a complete mock\n> environment and evolving FAPI-BR integration. It is not certified or\n> validated against real institutions; see [VALIDATION.md](https://github.com/brunovicco/openfinance-br-mcp/blob/main/VALIDATION.md)\n> before using it outside `environment=mock`.\n\n[![Python 3.12](https://img.shields.io/badge/python-3.12-blue.svg)](https://python.org)\n[![uv](https://img.shields.io/badge/managed%20by-uv-blueviolet)](https://github.com/astral-sh/uv)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n[![Ruff](https://img.shields.io/badge/lint-ruff-orange.svg)](https://github.com/astral-sh/ruff)\n\n---\n\n## What it is\n\nAn **MCP Server** that abstracts away the complexity of Open Finance Brasil (FAPI 1.0 Advanced, OAuth2, consent, mTLS) and exposes simple tools to Claude:\n\n```\nClaude → \"how much did I spend on food in March?\"\nClaude uses list_transactions(bank=nubank, categorize=true, date_from=2024-03-01)\nClaude → \"You spent R$ 847.30 on food in March...\"\n```\n\n## Supported banks\n\nThe mock environment simulates Nubank, Sicoob, Caixa, Banco do Brasil,\nBradesco, Itaú, Santander, XP, PicPay, and BTG Pactual with in-memory data and\nno network access. These are simulations, not certified integrations.\n\nReal adapters and the Payments API journey are experimental and unvalidated.\nPayments use the v5 `payments-consents`/`payments-pix` Directory families,\ndedicated per-consent tokens, verified response JWS, PAR/JAR, consent-payload\nbinding, and persistent idempotency.\n`list_pix_keys` is a demonstration extension rather than a standardized Open\nFinance Brasil endpoint. See [VALIDATION.md](https://github.com/brunovicco/openfinance-br-mcp/blob/main/VALIDATION.md)\nfor the exact scope.\n\n## Available MCP tools\n\nThe server exposes 18 tools grouped by journey:\n\n- **Accounts:** `list_accounts`, `get_balance`, `list_transactions`\n- **Cards:** `list_credit_cards`, `get_credit_card_bills`\n- **Investments:** `list_investments`, `list_funds`,\n  `list_variable_incomes`, `list_treasure_titles`\n- **PIX:** `list_pix_keys`, `initiate_pix`\n- **Data consent:** `start_consent`, `complete_consent`,\n  `check_consent_status`, `revoke_consent`\n- **Payment consent:** `start_payment_consent`, `complete_payment_consent`,\n  `check_payment_consent_status`\n\nIt also exposes the `openfinance://banks/` resource, the\n`analyze_monthly_spending` prompt, and optional URL elicitation when starting\nan authorization flow.\n\n## Quick start\n\n### Prerequisites\n\n- Python 3.12 or 3.13\n- [uv](https://github.com/astral-sh/uv) installed\n\n```bash\n# Run the published release in credential-free mock mode\nuvx --from openfinance-br-mcp==0.2.0 openfinance-mcp\n```\n\n### From source\n\n```bash\ngit clone https://github.com/brunovicco/openfinance-br-mcp.git\ncd openfinance-br-mcp\n\n# Optional: needed only for sandbox/production or DSPy categorization\ncp .env.example .env\n\n# Install dependencies\nuv sync\n\n# Run the server\nuv run openfinance-mcp\n```\n\n### Claude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"openfinance-br\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"openfinance-br-mcp==0.2.0\", \"openfinance-mcp\"]\n    }\n  }\n}\n```\n\n## Development\n\n```bash\n# Install with dev-dependencies\nuv sync\n\n# Run the tests\nuv run pytest tests/ -v\n\n# Lint and formatting\nuv run ruff check src/ tests/\nuv run black src/ tests/\n\n# Type check\nuv run mypy src/\n```\n\n## Containers and Kubernetes\n\n```bash\ndocker compose up openfinance-mcp\ndocker compose --profile test up\n```\n\nThe `k8s/` directory contains a two-replica Streamable HTTP example with\nRedis-backed state. Replace every credential, signing-key, OAuth issuer,\nresource-server, and domain placeholder before applying it. The server fails\nclosed when HTTP is exposed outside loopback without MCP client OAuth.\n\n## Architecture\n\n```\nClaude (MCP Client)\n        │ stdio or streamable-http\n        ▼\nopenfinance-br-mcp (MCP Server)\n  ├── Auth + Consent  (FAPI-BR 2.2.0: private_key_jwt, PAR/JAR, PKCE, mTLS)\n  ├── MCP Primitives  (18 tools + 1 resource + 1 prompt)\n  │   ├── Pydantic v2 input/output schemas\n  │   ├── Optional URL elicitation for bank authorization\n  │   └── Categorizer (DSPy + Claude for transaction classification)\n  ├── Bank Adapters   (10 banks - extensible)\n  └── Directory Client (resolves real bank endpoints from the BCB\n                         Directory of Participants)\n        │ HTTPS/mTLS\n        ▼\nOpen Finance BR (BCB) - Directory of Participants\n        │\n        ▼\n  Nubank · Sicoob · Caixa · + 100 participating institutions\n```\n\n## Environment variables\n\n| Variable | Required | Description |\n|----------|-------------|-----------|\n| `ENVIRONMENT` | ❌ | `mock` (default, no credentials needed), `sandbox`, or `production` |\n| `CLIENT_ID` | ⚠️ non-mock | Client ID registered with the institution |\n| `PRIVATE_KEY_PATH` | ⚠️ non-mock | RSA private key for `private_key_jwt`/JAR signing |\n| `PRIVATE_KEY_KID` | ⚠️ non-mock | `kid` matching the registered client JWKS |\n| `MTLS_CERT_PATH` | ⚠️ prod | Path to the mTLS certificate |\n| `MTLS_KEY_PATH` | ⚠️ prod | mTLS private key |\n| `ANTHROPIC_API_KEY` | ⚠️ DSPy | Required for `categorize=true` |\n| `REDIS_URL` | ❌ | Shares TokenStore/ConsentManager state across replicas |\n| `MCP_TRANSPORT` | ❌ | `stdio` (default) or `streamable-http` |\n| `MCP_HTTP_ALLOWED_ORIGINS` | ⚠️ remote HTTP | Required allowlist for any non-loopback bind |\n| `LANGFUSE_OTLP_ENDPOINT` | ❌ | Enables tracing to Langfuse (with `LANGFUSE_PUBLIC_KEY`/`LANGFUSE_SECRET_KEY`) |\n| `LOG_LEVEL` | ❌ | INFO, DEBUG, WARNING (default: INFO) |\n| `LOG_FORMAT` | ❌ | json or console (default: json) |\n\nSee [`.env.example`](https://github.com/brunovicco/openfinance-br-mcp/blob/main/.env.example)\nfor the full list.\n\n## Documentation\n\n- [Authorization](https://github.com/brunovicco/openfinance-br-mcp/blob/main/docs/en/authorization.md) - the two token universes and why they can never cross\n- [Contributing](https://github.com/brunovicco/openfinance-br-mcp/blob/main/CONTRIBUTING.md) - dev setup, CI checks, and adding an adapter\n- [Security](https://github.com/brunovicco/openfinance-br-mcp/blob/main/SECURITY.md) - scope, disclaimer, and vulnerability reporting\n- [Sources](https://github.com/brunovicco/openfinance-br-mcp/blob/main/SOURCES.md) - specifications and RFCs followed by the implementation\n- [Validation](https://github.com/brunovicco/openfinance-br-mcp/blob/main/VALIDATION.md) - what has and has not been validated\n- [Changelog](https://github.com/brunovicco/openfinance-br-mcp/blob/main/CHANGELOG.md) - release history\n- [Releasing](https://github.com/brunovicco/openfinance-br-mcp/blob/main/RELEASING.md) - maintainer release procedure\n\n## License\n\nMIT\n",
  "bytes": 7016,
  "sha": "8a61028108369e63c1d211663c841d29ce0c5a882771cd42d0df11431c55267e",
  "repo_slug": "brunovicco/openfinance-br-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_brunovicco_openfinance_br_mcp_0405f607/readme"
}