Despezzas MCP

• 📍 Visão geral

• Desenvolvimento com IA e agentes

• ⚡ Início rápido

• ✨ Funcionalidades

• 🧰 Catálogo de ferramentas

• 🛠 Tecnologias

  • Servidor MCP

  • Deploy

  • Ferramentas

• 🚀 Primeiros passos

  • 📦 Configuração

  • ✔️ Verificação

• 📋 Variáveis de ambiente

• 🔐 Autenticação

• 🖥 Configuração MCP local

• 🌐 Modo HTTP

• 🤖 Conexão OAuth com ChatGPT

• ☁️ Deploy remoto

• 🔎 Inspeção de HAR

• 📚 MCPs de referência

• 🤝 Contribuição

• 📄 Licença

📍 Visão geral

Servidor MCP para dados financeiros do Despezzas. Expõe ferramentas para clientes MCP (como ChatGPT) listarem contas, cartões e categorias, pesquisarem transações, consultarem resumos de gastos e fazerem operações de escrita com proteções.

Projeto open-source (MIT), construído analisando as requisições de rede e o código do frontend do Despezzas. O Despezzas não publica uma API oficial — trate isto como integração não oficial. Endpoints e campos podem mudar sem aviso.

Related MCP server: Lunch Money MCP Server

Desenvolvimento com IA e agentes

Este projeto foi desenvolvido de forma majoritariamente assistida por IA ("vibecoded"): grande parte da implementação foi gerada, refatorada ou iterada com agentes de IA, com direção técnica, conhecimento de programação e revisão manual de Guilherme Milek.

Para agentes de IA trabalhando neste repositório, use llms.txt como contexto inicial. Ele resume a arquitetura, arquivos principais, comandos, ferramentas MCP, regras de segurança e notas de deploy.

⚡ Início rápido

npm install
npm run build
Copy-Item .env.example .env
npm run dev

Depois configure a autenticação no .env com DESPEZZAS_TOKEN ou DESPEZZAS_EMAIL + DESPEZZAS_PASSWORD + DESPEZZAS_FIREBASE_API_KEY.

✨ Funcionalidades

📖 Ferramentas de leitura: perfil, acessos de perfil, configuração pessoal, contas, bancos, cartões de crédito, categorias, subcategorias, busca compacta de transações, visão geral, resumo financeiro e diagnóstico de exportação/campos.

🧾 Pré-visualização de transações: prepara payloads de criação/edição/exclusão sem chamar o Despezzas.

✍️ Ferramentas de escrita: trocar/criar/editar/excluir/sair de perfil, criar/editar/excluir conta, cartão de crédito, transação, transferência, duplicar transação e alternar pago.

🔐 Autenticação: token bearer copiado, login por e-mail/senha via variáveis de ambiente ou página HTTP de autorização MCP.

🔄 Renovação de token: sessões Firebase salvas são reutilizadas e renovadas automaticamente.

🛡 Trava de segurança: toda ferramenta de escrita/destrutiva exige confirm: true.

🔌 Transportes: stdio local e Streamable HTTP (Node ou Cloudflare Workers).

🔎 Depuração: inspetor de HAR e monitor de requisições no DevTools para capturar endpoints futuros.

Valores usam centavos inteiros no formato nativo do Despezzas. Exemplo: 12345 significa R$123.45.

Para escritas de transação, use primeiro as ferramentas de preparo:

1. Pesquise/liste a conta, cartão, categoria, subcategoria ou transação alvo.

2. Chame despezzas_prepare_create_transaction, despezzas_prepare_update_transaction ou despezzas_prepare_delete_transaction.

3. Revise o payload retornado e os IDs de destino.

4. Chame a ferramenta real de escrita com os mesmos campos e confirm: true.

despezzas_create_transaction recusa intencionalmente payloads sem destino de conta/cartão, com conta e cartão ao mesmo tempo, ou sem category_id, a menos que allow_uncategorized seja explicitamente true.

🧰 Catálogo de ferramentas

🛠 Tecnologias

As principais ferramentas usadas neste projeto:

Servidor MCP

Deploy

Ferramentas

* Veja o arquivo package.json para a lista completa de dependências.

🚀 Primeiros passos

📦 Configuração

npm install
npm run build
Copy-Item .env.example .env

✔️ Verificação

npm run verify
npm run smoke:readonly

npm run verify executa checagem de segurança do repositório, sincronização do catálogo MCP, Prettier, ESLint, TypeScript e testes. npm run smoke:readonly compila o projeto e chama apenas endpoints somente leitura do Despezzas usando o token/sessão configurado.

Checagens individuais úteis:

npm run check:repo-safety
npm run check:mcp-tools
npm run format:check
npm run lint
npm run typecheck
npm test

📋 Variáveis de ambiente

🔐 Autenticação

Opções preferenciais:

1. Execute em modo HTTP e abra http://127.0.0.1:8787/login.

2. Defina DESPEZZAS_EMAIL, DESPEZZAS_PASSWORD e DESPEZZAS_FIREBASE_API_KEY (chave pública — veja .env.example) no .env.

3. Copie o DESPEZZAS_TOKEN pelas DevTools do navegador.

A página /login usa a identidade visual do Despezzas, acompanha os temas claro/escuro do sistema e contém apenas os campos necessários para este MCP: e-mail, senha e, quando configurado, código de acesso do proprietário. Criação de conta e recuperação de senha ficam no app oficial do Despezzas.

O fluxo de login espelha o frontend do Despezzas:

1. POST https://api.despezzas.com/v2/auth com e-mail/senha.

2. Usa o firebase_token retornado com Firebase accounts:signInWithCustomToken usando DESPEZZAS_FIREBASE_API_KEY (a chave pública do Firebase Web do Despezzas).

3. Usa o idToken do Firebase como Authorization: Bearer ... em api.despezzas.com.

4. Salva o refresh token do Firebase em %USERPROFILE%\.despezzas-mcp\session.json por padrão.

Defina DESPEZZAS_SESSION_FILE=none para desativar a persistência de sessão. Se todos os métodos de autenticação falharem, despezzas_status indicará que é preciso abrir a página de login ou configurar credenciais.

Não passe sua senha como argumento de ferramenta. Argumentos podem ficar visíveis ao cliente. Use .env ou a página /login.

🖥 Configuração MCP local

Para um cliente MCP local via stdio:

{
  "mcpServers": {
    "despezzas": {
      "command": "node",
      "args": ["C:\\caminho\\para\\despezzas-mcp\\dist\\index.js"],
      "env": {
        "DESPEZZAS_TOKEN": "seu-token-aqui"
      }
    }
  }
}

Para desenvolvimento sem compilar:

npm run dev

🌐 Modo HTTP

$env:MCP_TRANSPORT = "http"
$env:PORT = "8787"
npm run dev:http

Verificação de saúde:

Invoke-RestMethod http://127.0.0.1:8787/health

Abra a página local de autorização:

Start-Process http://127.0.0.1:8787/login

Se expuser o modo HTTP além do localhost, coloque HTTPS e controle de acesso na frente. A página /login aceita sua senha do Despezzas para autorizar o MCP.

🤖 Conexão OAuth com ChatGPT

Para a tela New App em ChatGPT Apps & Connectors:

1. Faça deploy em Cloudflare Workers seguindo docs/cloudflare-workers.md.

   npm run check:cloudflare
   npm run deploy:cloudflare

2. Confirme a URL pública do Worker:

   Invoke-RestMethod https://despezzas-mcp.<sua-conta>.workers.dev/health

3. No ChatGPT, use:

   • URL do servidor: https://despezzas-mcp.<sua-conta>.workers.dev/mcp

   • Autenticação: OAuth

O servidor expõe os endpoints de descoberta esperados pelo ChatGPT:

• GET /.well-known/oauth-protected-resource

• GET /.well-known/oauth-authorization-server

• POST /oauth/register

• GET|POST /oauth/authorize

• POST /oauth/token

Essa camada OAuth protege a conexão. Durante a autorização, a página de login troca e-mail/senha do Despezzas por uma sessão Despezzas/Firebase no servidor. O botão final é Entrar e autorizar, e o ChatGPT recebe apenas um token de acesso MCP opaco.

MCP_HTTP_BEARER_TOKEN ainda é útil para scripts fora do ChatGPT. Quando omitido, o /mcp exige um token OAuth válido.

Apps/conectores personalizados do ChatGPT exigem um endpoint MCP remoto em HTTPS. A documentação do Apps SDK da OpenAI descreve o MCP como a camada de servidor necessária para expor ferramentas ao ChatGPT, e o guia de conexão pelo ChatGPT usa um endpoint HTTPS para adicionar um servidor MCP. Veja:

• Quickstart do Apps SDK

• Construir seu servidor MCP

• Autenticar usuários

• Conectar pelo ChatGPT

• Construção de servidores MCP para ChatGPT Apps e integrações de API

• Especificação de autorização MCP

☁️ Deploy remoto

Caminho suportado para deploy remoto: Cloudflare Workers.

Veja docs/deployment.md para o resumo operacional do deploy apenas em Cloudflare.

Arquivos de deploy mantidos:

• wrangler.jsonc e src/cloudflare.ts para Cloudflare Workers.

• docs/cloudflare-workers.md para o passo a passo completo.

Para o modo multiusuário em Cloudflare Workers, associe o namespace KV DESPEZZAS_SESSIONS, defina MCP_OAUTH_TOKEN_SECRET, SESSION_ENCRYPTION_KEY e DESPEZZAS_FIREBASE_API_KEY como secrets do Wrangler e faça deploy com npm run deploy:cloudflare. Para deploys privados de conta única, defina MCP_OWNER_AUTH_CODE junto com suas credenciais do Despezzas e DESPEZZAS_FIREBASE_API_KEY.

🔎 Inspeção de HAR

Quando capturar mais ações do frontend:

npm run inspect:har -- C:\path\to\despezzas.har

O script imprime apenas chamadas para api.despezzas.com e mascara segredos comuns. Próximas ações úteis para capturar:

• Pagar/despagar contas e faturas de cartão de crédito.

• Metas, limites de gastos, relatórios, investimentos, gerenciamento de conexão Open Finance e ações do chat de IA.

• Qualquer caso de borda de perfil ainda não coberto por despezzas_list_profiles / despezzas_switch_profile / ferramentas de gerenciamento de perfil.

Se preferir não exportar um HAR, cole scripts/request-monitor-devtools.js no DevTools em despezzas.com, execute a ação e depois rode:

window.__despezzasMcpMonitor.download();

Ele exporta um relatório JSON mascarado das chamadas fetch/XHR para api.despezzas.com.

📚 MCPs de referência

Este projeto tomou como referência:

• SamuelMoraesF/mcp-organizze

• silviorodrigues/organizze-mcp

• WeslleyNasRocha/organizze-mcp

Este repositório mantém uma estrutura parecida, mas usa endpoints nativos do Despezzas e IDs em UUID.

🤝 Contribuição

Contribuições são bem-vindas. Antes de abrir um pull request:

1. Leia CONTRIBUTING.md.

2. Rode npm run verify.

3. Não inclua credenciais, tokens, sessões, HARs não mascarados ou dados financeiros reais.

4. Mantenha confirm: true obrigatório para toda ferramenta de escrita/destrutiva.

5. Atualize llms.txt, AGENTS.md e os docs em docs/ quando mudar arquitetura, comandos, ferramentas MCP ou regras importantes para agentes.

📄 Licença

MIT. Veja LICENSE.