Cadê Meu Dinheiro

Servidor MCP que sincroniza os dados bancários da sua conexão Meu Pluggy para um Postgres próprio e responde, dentro do Claude Desktop/Code, à pergunta que importa: "para onde foi meu dinheiro esse mês?". Além do resumo de gastos por categoria com comparação mês a mês, dá para definir orçamentos por categoria, buscar transações e criar regras permanentes de categorização que são reaplicadas ao histórico.

São três camadas em um processo Node: o sync (Pluggy → Postgres, via cron de 6 em 6 horas, com janela de sobreposição de 7 dias), o motor de insights (funções puras sobre os dados já persistidos) e a interface MCP (Streamable HTTP protegido por bearer token).

O fluxo de branches, o padrão de commit e o que nunca entra no repositório estão em CONTRIBUTING.md.

Pré-requisitos

Conta no Meu Pluggy com os bancos e cartões já conectados.
Credenciais de API (clientId e clientSecret) em dashboard.pluggy.ai.
Os item IDs de cada conexão bancária, copiados do dashboard — é o que o sync percorre.
Node 22+ e Docker.

Setup local

cp .env.example .env     # preencha as credenciais e o token
docker compose up -d postgres
npm install
npm run dev

O MCP_BEARER_TOKEN deve ser gerado com openssl rand -hex 32.

Nenhuma contraparte vem cadastrada. O padrão que identifica você mesma é o seu nome, e nome de ninguém entra em repositório — cadastre o seu na primeira conversa com o Claude: "marca PIX pra FULANO DE TAL como conta minha" dispara set_internal_counterparty e reclassifica o histórico inteiro.

Se alguma porta do host já estiver ocupada por outro projeto, todas são configuráveis no .env: POSTGRES_HOST_PORT, MCP_HOST_PORT, N8N_HOST_PORT, WAHA_HOST_PORT.

Testes

Os testes de repositório rodam contra o banco cade_test do compose, então o Postgres precisa estar de pé:

docker compose up -d postgres
npm test

Deploy na VPS

docker compose up -d --build

Sobe o Postgres, o servidor MCP (porta 3333), o n8n e o WAHA. Confira com curl http://localhost:3333/health e docker compose logs mcp-server.

Conectando ao Claude

Claude Code:

claude mcp add --transport http cade-meu-dinheiro http://SEU_IP:3333/mcp --header "Authorization: Bearer SEU_TOKEN"

Claude Desktop: Settings → Connectors → Add custom connector, com a mesma URL e o mesmo header Authorization.

Depois disso, pergunte "para onde foi meu dinheiro esse mês?" — o Claude chama get_spending_summary e responde com os seus números.

Tools disponíveis

Tool	O que faz
`get_spending_summary`	Gastos do mês por categoria, delta vs. mês anterior e top estabelecimentos
`get_budget_status`	Orçamento vs. realizado, com projeção linear de fim de mês
`search_transactions`	Busca por texto, conta, categoria e período; devolve `total` (só gasto) e `totalMovimentado` (tudo)
`analyze_spending`	Soma, contagem e média de gastos, com agrupamento por mês, categoria ou conta
`query_finances`	Um `SELECT` livre sobre o banco (somente leitura, 200 linhas, 3s) para o que as outras não cobrem
`set_budget`	Define o limite mensal de uma categoria
`set_category_rule`	Cria regra de categorização e reaplica ao histórico
`set_internal_counterparty`	Marca um padrão como conta sua: deixa de contar como gasto ou renda
`remove_internal_counterparty`	Desfaz a marcação acima e reclassifica o histórico
`set_income_pattern`	Marca um padrão de entrada como renda de verdade
`remove_income_pattern`	Desfaz a marcação acima e reclassifica o histórico

Toda resposta vem com um bloco de frescor dizendo até quando cada conta tem dado — número nenhum aparece sem data.

Gasto não é sinal negativo, é kind: cada transação é classificada em consumo, transferencia_terceiro, movimentacao_interna, credito_tomado, fatura_sem_detalhe, renda, entrada_nao_renda ou nao_classificado. Contam como gasto apenas consumo, transferencia_terceiro, credito_tomado e fatura_sem_detalhe — então PIX entre contas suas e pagamento de fatura de cartão que já reporta as compras param de ser contados como dinheiro gasto.

Há também o prompt financial-coach, que carrega a persona de coach financeiro já com o seu contexto de orçamento do mês.

Segurança

Token forte e único (openssl rand -hex 32); trate-o como senha do seu extrato bancário.
Nunca commite o .env — ele está no .gitignore e deve continuar lá.
Screenshots e gravações públicas só com dados de sandbox da Pluggy, nunca com os seus.

n8n e WAHA (Fase 2)

Os dois já sobem no compose para você explorar desde já: n8n em http://localhost:5678 e WAHA em http://localhost:3000. As portas ficam presas a 127.0.0.1, então na VPS o acesso é por túnel SSH:

ssh -L 5678:localhost:5678 usuario@vps

Apple Silicon: a tag padrão do WAHA só tem build amd64. No .env, use WAHA_IMAGE=devlikeapro/waha:noweb-arm (engine NOWEB, sem Chromium). Fixe também WAHA_API_KEY e WAHA_SWAGGER_PASSWORD, senão o WAHA sorteia credenciais novas a cada boot e o n8n perde o acesso.

Os workflows de alerta por WhatsApp chegam na Fase 2.