Copiloto Financeiro

🇺🇸 Read in English

Copiloto financeiro pessoal, self-hosted, feito para o Brasil. Puxa transações bancárias via Pluggy (Open Finance Brasil) e acompanha gastos, contas, dívidas, metas e projeção de fluxo de caixa da família — uma visão por pessoa, mais uma combinada.

Bun workspace: backend/ (API Elysia + sync com o Pluggy + servidor MCP), frontend/ (Vite + React), shared/ (tipos compartilhados). Veja ARCHITECTURE.md (em inglês) / backend/API-ARCHITECTURE.md pros detalhes internos, CONTRIBUTING.md antes de abrir um PR.

Filosofia

Construído com agente de IA em primeiro lugar: toda operação é uma ferramenta MCP (backend/src/mcp-server.ts) antes de ser uma rota REST — o Claude opera direto hoje, qualquer agente com MCP poderia. Vem só com o básico e é deliberadamente não opinativo além disso; bifurque e mude o código se algo não bater com o seu dinheiro.

Related MCP server: @gu-does-packages/pluggy-mcp

Configuração

O jeito mais simples: mande o link deste repositório pro Claude Code e peça pra ele configurar — ele cuida de tudo (/get-started).

Prefere fazer à mão?

1. bun install, depois copie .env.example pra .env (os padrões já servem).

2. bun run dev, acesse a URL impressa e defina uma senha. Isso criptografa o banco de dados — salve o código de recuperação que aparece, ele é o único jeito de entrar se você esquecer a senha e nunca é mostrado de novo.

3. Pra usar pelo Claude Code (MCP): em /config → "Chaves de API", gere uma chave e salve ela (só aparece uma vez) em data/mcp-api-key — só a chave, mais nada.

4. Adicione pessoas e suas conexões com o Pluggy (um Item ID via meu-pluggy) em /config.

Sem contas — só essa senha. O sync roda quando você desbloqueia, se já faz um tempo (ou quando quiser, em "Sincronizar agora"). Bloquear o app corta o acesso do MCP também. Feito pra ficar na sua máquina ou rede local, não na internet aberta (veja "Deploy").

Desenvolvimento

• bun run dev / bun run dev:backend / bun run dev:frontend

• bun run build / bun run start — build de produção + servir

• bun run typecheck / bun run test / bun run lint

Deploy

docker compose up -d --build

Builda a imagem, roda as migrations ao iniciar, serve em 127.0.0.1:8080 e persiste ./data (o banco criptografado, o arquivo necessário pra desbloqueá-lo e a chave do MCP — faça backup disso como uma unidade só). Ainda sem contas, então não exponha isso na internet aberta — mantenha em localhost/rede local, ou acesse remotamente com algo como Tailscale.