grana-mcp
Supports importing Nubank credit card and account CSV exports via the nubank-cartao and nubank-conta formats, enabling analysis of exported Nubank transactions.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
grana-mcp
Servidor MCP open source, local e somente leitura para finanças pessoais no Brasil. Você pergunta ao seu cliente MCP (Claude Code, Claude Desktop, Cursor etc.) coisas como "onde gastamos mais esse mês?" ou "quanto está a fatura do cartão?", e as respostas vêm das suas próprias contas, via Open Finance, pelo Meu Pluggy, que é gratuito para uso pessoal.
Por que mais um MCP da Pluggy?
Configuração guiada:
grana-mcp initleva você do zero ao primeiro sync.Casal ou família: contas de várias pessoas numa visão só, com o gasto separado por dono da conta.
Limpeza feita para o Brasil: tira do gasto o pagamento de fatura (que contaria tudo duas vezes), as transferências entre as pessoas da casa, aplicações em caixinhas/CDB e compras estornadas; conta cada parcela no mês em que é cobrada; categoriza estabelecimentos brasileiros.
Privacidade primeiro: as transações ficam num SQLite no seu computador; o LLM recebe totais por padrão, e nomes de pessoas de fora da casa são mascarados. Veja docs/privacy.md.
Sem Pluggy, se preferir: importa OFX e CSV exportados do banco.
Related MCP server: openfinance-analyst
Instalação
Precisa do uv e de Python 3.12+.
uvx grana-mcp initO assistente explica o Meu Pluggy, abre as páginas, pede o Client ID/Secret (o secret vai para o keyring do sistema), testa a conexão e roda o primeiro sync. O passo a passo detalhado está em docs/setup-meu-pluggy.md.
Depois, adicione o servidor no seu cliente MCP. No Claude Code:
claude mcp add grana --scope user -- uvx grana-mcp serveEm outros clientes, o comando do servidor stdio é uvx grana-mcp serve.
O servidor só lê o SQLite local e não acessa a rede. Para manter os dados em dia, agende o sync uma vez por dia (o Meu Pluggy atualiza a cada 24 h):
grana-mcp sync # por exemplo, no cron: 0 7 * * * uvx grana-mcp sync
grana-mcp doctor # confere credenciais, autorização, permissões e schemaO que dá para perguntar
Ferramenta | Para quê |
| Gasto do período por categoria, estabelecimento, pessoa, perfil ou conta |
| Um mês contra outro, por categoria |
| Onde mais se gastou, em valor e em frequência |
| Assinaturas e cobranças mensais, com mudança de preço |
| Faturas fechadas, estimativa da fatura aberta e parcelas futuras |
| O que ficou fora do gasto e por quê |
| Lançamentos individuais (no máximo 50, com filtro obrigatório) |
| Conexões, contas, donos, último sync e validade da autorização |
| Corrige uma categoria (única ferramenta que grava, e só no banco local) |
Prompt pronto: relatorio_mensal ("faz o relatório de outubro").
Casal ou família
Uma conta do Meu Pluggy pode trazer bancos de mais de uma pessoa. Diga quem é dono de cada conta:
grana-mcp person add "Ana"
grana-mcp person add "Bia"
grana-mcp account list
grana-mcp account assign 0001 ana # id da conta ou final do númeroAs transferências entre vocês são reconhecidas pelo CPF dos titulares, que o sync lê da Pluggy e guarda só como hash. Se precisar, cadastre na mão: grana-mcp household add-doc ana (pede o CPF sem mostrar na tela).
Categorias
Sem LLM, nesta ordem: suas regras → regras embutidas para estabelecimentos brasileiros (categories_br.toml) → categoria da Pluggy traduzida → "Outros". Para corrigir:
grana-mcp category add "padaria do bairro" Mercado # palavras inteiras; "uber*" = prefixo
grana-mcp category list
grana-mcp category remove 3Ou peça ao seu cliente MCP: "coloca a padaria do bairro em Mercado".
Sem Pluggy: OFX e CSV
grana-mcp import-ofx extrato.ofx --profile ana --person ana
grana-mcp import-csv fatura.csv --profile ana --format nubank-cartaoFormatos de CSV: nubank-cartao, nubank-conta e generic (date,description,amount). Reimportar o mesmo arquivo não duplica. Não importe uma conta que também é sincronizada pela Pluggy, senão tudo conta duas vezes.
Chat no celular (opcional)
grana-mcp web serve sobe uma página de chat em que o Claude Code responde usando só as ferramentas do grana. Ela foi feita para rodar num container Podman e ser acessada pelo celular via WireGuard, nunca exposta na internet. Veja docs/web.md.
Software, não serviço
O grana-mcp é só software. Não existe versão hospedada: cada pessoa roda na própria máquina, com a própria conta da Pluggy, e os mantenedores não operam nada nem recebem dado nenhum. O que o seu cliente MCP recebe vai para o provedor do LLM que você usa (Anthropic, OpenAI etc.); por isso o padrão é enviar só valores somados.
Desenvolvimento
uv sync
uv run pytest
uv run ruff check && uv run mypy
uvx pre-commit install # bloqueia commit de banco, extrato e CPFOs testes usam só dados sintéticos. Nunca commite dados reais, nem anonimizados.
Créditos
Aprendizados sobre a API da Pluggy e o Meu Pluggy vieram de projetos MIT: TrainedLoop/cashbook-mcp e brunopedrazza/pluggy-mcp-server.
Licença
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
Ask your AI about Brazilian bank spending. Read-only bank access, never moves money. Paid plan.
Chat with your bank data: balances, transactions, budgets, bills. Reads only, never moves money.
Brazilian personal & business finance with Open Finance: transactions, cards, investments.
Brazilian Open Finance MCP — 30+ banks (Itaú, Nubank, etc.) to Claude/Cursor. Read-only.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables natural language queries to read balances, statements, credit card bills, investments, and loans from Next bank accounts via Open Finance Brasil. All read-only, no money movement.MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for personal finance via Open Finance, consolidating accounts and cards and answering spending questions with aggregated numbers. Provides tools for category spending, recurring subscriptions, budgets, card bills, and installment forecasts, with data stored locally in an encrypted SQLite database.2ISC
- AlicenseNot gradedqualityBmaintenanceEnables read-only access to your own BTG Pactual account through the bank's web app, exposing balances, statements, cards, invoices with installments, investment positions and Open Finance holdings as local cached data. Questions are answered without repeated bank calls and keep working after the bank session expires.MIT
- AlicenseNot gradedqualityCmaintenanceEnables natural-language access to personal finance data, including consolidated balances, monthly overviews, transaction search, credit card invoices, recurring bills, budgets, category/tag reports, cash flow forecasts, and Open Finance status, with optional read/write tools.MIT