Skip to main content
Glama
grana-mcp

grana-mcp

by glkwolff

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 init leva 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 init

O 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 serve

Em 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 schema

O que dá para perguntar

Ferramenta

Para quê

spending_summary

Gasto do período por categoria, estabelecimento, pessoa, perfil ou conta

compare_periods

Um mês contra outro, por categoria

top_merchants

Onde mais se gastou, em valor e em frequência

recurring_charges

Assinaturas e cobranças mensais, com mudança de preço

card_bills

Faturas fechadas, estimativa da fatura aberta e parcelas futuras

excluded_items

O que ficou fora do gasto e por quê

find_transactions

Lançamentos individuais (no máximo 50, com filtro obrigatório)

status

Conexões, contas, donos, último sync e validade da autorização

set_category_rule

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úmero

As 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 3

Ou 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-cartao

Formatos 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 CPF

Os 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

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP 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.
      2
      ISC
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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