openfinance-br-mcp

MCP Server para o Open Finance Brasil — conecta o Claude diretamente às APIs do Banco Central, cobrindo Fases 2, 3 e 4.

---

O que é

Um MCP Server que abstrai toda a complexidade do Open Finance Brasil (FAPI 1.0 Advanced, OAuth2, consentimento, mTLS) e expõe tools simples para o Claude:

Claude → "quanto gastei com alimentação em março?"
Claude usa list_transactions(bank=nubank, categorize=true, date_from=2024-03-01)
Claude → "Você gastou R$ 847,30 com alimentação em março..."

Bancos suportados

Banco	ISPB	Fase 2	Fase 3 (PIX)	Fase 4 (Investimentos)
Nubank	18236120	✅	✅	✅
Sicoob	07853842	✅	✅	✅
Caixa Econômica	00360305	✅	✅	✅

Novos bancos: implemente BankAdapter e registre em server.py.

Tools MCP disponíveis

Tool	Descrição	Fase
list_accounts	Lista contas corrente, poupança e pré-paga	2
get_balance	Saldo disponível, bloqueado e investido	2
list_transactions	Extrato com filtros e categorização DSPy	2
list_credit_cards	Cartões de crédito e limites	2
get_credit_card_bills	Faturas abertas e anteriores	2
list_pix_keys	Chaves PIX cadastradas	2
initiate_pix	Pagamento PIX com idempotência	3
list_investments	Renda fixa (CDB, LCI, LCA)	4

Instalação rápida

Pré-requisitos

• Python 3.12+
• uv instalado

# Clone o repositório
git clone https://github.com/seu-usuario/openfinance-br-mcp.git
cd openfinance-br-mcp

# Configure o ambiente
cp .env.example .env
# Edite .env com seu CLIENT_ID, CLIENT_SECRET etc.

# Instale as dependências
uv sync

# Execute o servidor
uv run openfinance-mcp

Claude Desktop

Adicione ao ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "openfinance-br": {
      "command": "uv",
      "args": ["run", "--directory", "/caminho/para/openfinance-br-mcp", "openfinance-mcp"],
      "env": {
        "CLIENT_ID": "seu_client_id",
        "CLIENT_SECRET": "seu_client_secret",
        "MTLS_ENABLED": "false"
      }
    }
  }
}

Desenvolvimento

# Instala com dev-dependencies
uv sync

# Roda os testes
uv run pytest tests/ -v

# Lint e formatação
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 .

# Roda (testes)
docker compose --profile test up

# Roda o servidor
docker compose up openfinance-mcp

Kubernetes

# Cria o namespace
kubectl create namespace fintech

# Aplica configurações (edite os secrets antes!)
kubectl apply -f k8s/config-and-secrets.yaml
kubectl apply -f k8s/deployment.yaml

Arquitetura

Claude (MCP Client)
        │ stdio
        ▼
openfinance-br-mcp (MCP Server)
  ├── Auth + Consent  (OAuth2/FAPI 1.0, PKCE, mTLS)
  ├── MCP Tools       (8 tools, input validado por Pydantic v2)
  │   └── Categorizer (DSPy + Claude para classificar transações)
  └── Bank Adapters   (Nubank, Sicoob, Caixa — extensível)
        │ HTTPS/mTLS
        ▼
Open Finance BR (BCB) — api.banco.com.br/open-banking
        │
        ▼
  Nubank · Sicoob · Caixa · + 800 IFs

Princípios de design

• SOLID: BankAdapter ABC (O/C, LSP), tools com SRP, DI via construtor
• 12-Factor: config via env, stateless, logs em stdout
• Clean Code: docstrings Google style, sem magic numbers, funções pequenas
• Segurança: mTLS, SecretStr, tokens em memória, PKCE obrigatório
• Idempotência: asyncio.Lock no refresh de tokens, X-Idempotency-Key no PIX
• DSPy: categorização de transações como problema de classificação LLM

Variáveis de ambiente

Variável	Obrigatório	Descrição
CLIENT_ID	✅	Client ID registrado na IF
CLIENT_SECRET	✅	Client secret
MTLS_CERT_PATH	⚠️ prod	Caminho do certificado mTLS
MTLS_KEY_PATH	⚠️ prod	Chave privada mTLS
ANTHROPIC_API_KEY	⚠️ DSPy	Necessário para categorize=true
LOG_LEVEL	❌	INFO, DEBUG, WARNING (padrão: INFO)
LOG_FORMAT	❌	json ou console (padrão: json)

Adicionando um novo banco

1. Crie src/openfinance_br_mcp/adapters/meu_banco.py
2. Herde de NubankAdapter (ou BankAdapter para implementação completa)
3. Sobrescreva bank_id, base_url e token_endpoint
4. Registre em server.py dentro de _build_server()

Licença

MIT