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

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