openfinance-analyst

MCP server que consolida suas contas e cartões de várias instituições via Open Finance e responde perguntas de gasto com números agregados — não com listas de transações.

"pra onde foi meu dinheiro em junho?"
"gastei mais com comida que no mês passado?"
"que assinaturas subiram de preço?"
"quanto do meu agosto já está comprometido com parcelas?"

Por que passa pela Pluggy

Consumir as APIs do Open Finance Brasil diretamente exige ser instituição autorizada pelo BACEN, registrada no Diretório de Participantes, com certificados ICP/OFB, mTLS e FAPI. Pessoa física não se cadastra.

O Meu Pluggy resolve isso: a Pluggy é participante regulado e dá acesso gratuito, sem prazo de expiração, aos dados do seu próprio CPF.

Isto é de uso pessoal, um CPF. Servir outras pessoas cai no plano comercial da Pluggy (a partir de R$ 2.500/mês). O projeto é somente leitura — nenhuma tool inicia pagamento.

O trial de 14 dias não se aplica a você (se você conectar do jeito certo)

O trial cobre os recursos comerciais — conectar contas de outras pessoas. Acabado o trial, "as conexões com contas reais de clientes pausam até você ativar um plano". O acesso aos seus próprios dados é outra coisa: "o Meu Pluggy e o acesso à API através dele são gratuitos por tempo indeterminado, sem prazo de expiração", via Conector 200.

A armadilha é que o dashboard deixa criar a conexão dos dois jeitos, e o caminho errado é o mais intuitivo:

O MCP detecta isso: se alguma conexão não for o conector 200, toda resposta de análise passa a carregar um aviso explicando que ela vai pausar. Você descobre no primeiro sync, não no dia 15.

Related MCP server: bank.mcp

Setup

São dois portais separados, com cadastros separados. meu.pluggy.ai é só o consentimento — ele não expõe credencial de API e não é onde você a procura. As credenciais nascem no dashboard.pluggy.ai.

1. Conecte seus bancos em meu.pluggy.ai — fluxo oficial de consentimento do Open Finance. O MCP nunca vê sua senha de banco.

2. Crie a aplicação em dashboard.pluggy.ai (outro cadastro) → aba Applications → nova aplicação. CLIENT_ID e CLIENT_SECRET aparecem aqui.

3. Adicione o conector MeuPluggy à lista de conectores da aplicação.

4. Vincule e pegue o item ID. Na aplicação, clique em "Ir para Demo", faça login com a conta do Meu Pluggy e autorize — isso cria o Item. Depois, no menu de três pontos (canto superior direito) → "Copiar Item ID".

Esse último passo não está na documentação da Pluggy. O itemId não aparece em nenhuma tela óbvia do dashboard, e o SDK não tem fetchItems() para descobri-lo — por isso ele precisa ser declarado uma vez em PLUGGY_ITEM_IDS. Depois do primeiro sync fica salvo no banco local e você não precisa mais dele.

5. Instale:

npm install && npm run build

6. Registre no Claude Code:

claude mcp add openfinance-analyst -- node /caminho/para/openfinance-analyst/dist/index.js

Com as variáveis de ambiente:

7. Rode a tool sync uma vez. O primeiro sync faz backfill de 24 meses.

As tools

Dashboard

npm run build && npm run dash

Sobe um servidor local e abre o navegador. A página tem um botão Atualizar que roda o sync e recarrega os números — sem LLM no caminho.

Quatro painéis: fluxo de caixa dos últimos 12 meses, contas e cartões com a fatura aberta, gastos do mês contra o anterior, e parcelas comprometidas mais recorrências detectadas.

Sobre as credenciais: o MCP recebe as suas por variável de ambiente, injetadas pelo Claude Code. Um comando de shell comum não herda nada disso, então o dash também procura no Keychain — que é o que os dois enxergam. Para gravá-las lá:

security add-generic-password -U -s openfinance-analyst -a pluggy-client-id     -w '<seu client id>'
security add-generic-password -U -s openfinance-analyst -a pluggy-client-secret -w '<seu secret>'
security add-generic-password -U -s openfinance-analyst -a pluggy-item-ids      -w '<ids,separados,por,vírgula>'

Sem credencial nenhuma o dashboard ainda abre, em modo leitura: os dados já sincronizados estão no banco local. Só o botão Atualizar falha, dizendo o porquê.

O token vive só na sessão: fechou o processo, a URL antiga não vale mais. Requisição sem ele recebe 403 — sem isso, qualquer página aberta no seu navegador poderia tentar ler localhost.

O dashboard chama exatamente as mesmas funções de src/analysis/ que as tools MCP chamam. Número que divergir entre a página e o Claude é bug, não interpretação.

Decisões que valem conhecer

Os dados ficam no seu disco, cifrados. SQLite com SQLCipher, chave no Keychain do macOS, arquivo 600 em ~/.openfinance-analyst/. As tools de análise leem só do banco local — nunca da rede — o que torna a resposta rápida, barata e determinística.

Cartão de crédito inverte o sinal. Na Pluggy, valor positivo em cartão significa nova compra; em conta corrente significa entrada. Tudo é normalizado na entrada para uma regra única: gasto negativo, entrada positiva. Somar sem isso mistura despesa com receita silenciosamente.

Nenhum número velho passa por fresco. Consentimento do Open Finance expira em 12 meses e conexão cai sozinha. Toda resposta de análise carrega um campo avisos dizendo qual instituição está desatualizada, precisa de reautorização, ou está com consentimento perto de vencer.

Sync é por upsert, nunca insert. Transação não é imutável: nasce PENDING, vira POSTED, e a descrição às vezes é enriquecida depois. Cada sync revisita os últimos 35 dias; a chave é o id da Pluggy, então rodar duas vezes não duplica nada.

Agrupamento mensal em America/Sao_Paulo. Em UTC, compra de dia 1º à 0h30 cairia no mês anterior.

Desenvolvimento

npm test          # 105 testes
npm run typecheck
npm run build

O módulo analysis/ é puro — sem I/O, sem rede, sem banco. É onde mora a lógica que produz os números e é onde mora a maior parte dos testes.

Spec e plano de implementação em docs/superpowers/.

Removendo

rm -rf ~/.openfinance-analyst
security delete-generic-password -s openfinance-analyst