Despezzas MCP

<!-- ===== HEADER ===== --> <p align="right"> <a href="./README.en.md" title="Read the README in English"><img src="https://img.shields.io/badge/lang-en-gray?style=flat-square&labelColor=202024" alt="lang-en" /></a> <img src="https://img.shields.io/badge/lang-pt--br-green?style=flat-square&labelColor=202024" alt="lang-pt-br" /> </p>

<p align="center"> <img src="./assets/despezzas-mcp.png" alt="Despezzas MCP logo" width="120" /> </p>

<h1 id="top" align="center">Despezzas MCP</h1>

<p align="center"> <img src="https://img.shields.io/badge/languages-4-04D361?style=flat-square&labelColor=202024" alt="Repository language count" /> <img src="https://img.shields.io/badge/repo%20size-207%20KiB-007ec6?style=flat-square&labelColor=202024" alt="Repository size" /> <img src="https://img.shields.io/github/commit-activity/m/guipmilek/despezzas-mcp?style=flat-square&color=black&labelColor=202024" alt="Commit activity" /> <a href="https://github.com/guipmilek/despezzas-mcp/commits/main" title="Ver commits do repositório"><img src="https://img.shields.io/badge/last%20commit-today-4b0?style=flat-square&labelColor=202024" alt="Last commit" /></a> <a href="./LICENSE" title="Ver licença do projeto"><img src="https://img.shields.io/badge/license-MIT-brightgreen?style=flat-square&labelColor=202024" alt="Project license" /></a> <img src="https://img.shields.io/badge/Node.js-%3E%3D20-233056?style=flat-square&logo=node.js&logoColor=white&labelColor=202024" alt="Node.js >= 20" /> </p>

<p align="center"> Servidor MCP não oficial para conectar dados financeiros do Despezzas a clientes compatíveis com MCP, incluindo ChatGPT. </p>

<details> <summary> <h2>📒 Sumário</h2> </summary>

• 📍 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

</details>

<!-- ===== PROJECT INFOS ===== -->

📍 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.

[!WARNING] Integração não oficial. Endpoints e fluxos de login podem mudar sem aviso.

[!IMPORTANT] Este MCP pode ler e alterar dados financeiros pessoais. Nunca faça commit de .env, tokens, senhas, sessões, HARs não mascarados ou respostas reais da API.

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.

Item	Valor
Status	MVP funcional para uso pessoal
API	Integração não oficial com endpoints do Despezzas
Runtime	Node.js >=20
Transportes	stdio, HTTP Node, Cloudflare Workers
Autenticação	Bearer token, e-mail/senha, OAuth MCP
Deploy recomendado	Cloudflare Workers

⚡ 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

Grupo	Exemplos	Escrita?	Observação
Status e perfil	despezzas_status, despezzas_profile, despezzas_list_profiles	Parcial	Trocar/criar/excluir perfil exige confirm: true.
Contas e cartões	despezzas_list_accounts, despezzas_list_credit_cards, despezzas_create_account	Parcial	Escritas validam IDs e confirmação.
Categorias	despezzas_list_categories, despezzas_list_subcategories	Não	Use antes de criar/editar transações.
Transações	despezzas_search_transactions, despezzas_create_transaction, despezzas_update_transaction	Parcial	Criação exige destino, categoria ou allow_uncategorized.
Pré-visualização	despezzas_prepare_create_transaction, despezzas_prepare_update_transaction	Não	Caminho recomendado antes de qualquer escrita.
Diagnóstico	despezzas_export_transactions, despezzas_raw_api	Parcial	Use com cuidado; respostas são mascaradas quando possível.

🛠 Tecnologias

As principais ferramentas usadas neste projeto:

Servidor MCP

<p> <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-white?style=for-the-badge&logo=TypeScript" alt="TypeScript" /></a> <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-233056?style=for-the-badge&logo=node.js&logoColor=white" alt="Node.js" /></a> <a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/Model_Context_Protocol-202024?style=for-the-badge" alt="Model Context Protocol" /></a> <a href="https://expressjs.com/"><img src="https://img.shields.io/badge/Express-111111?style=for-the-badge&logo=express&logoColor=white" alt="Express" /></a> <a href="https://hono.dev/"><img src="https://img.shields.io/badge/Hono-e36002?style=for-the-badge" alt="Hono" /></a> <a href="https://github.com/colinhacks/zod"><img src="https://img.shields.io/badge/Zod-3068b7?style=for-the-badge&logo=zod&logoColor=white" alt="Zod" /></a> </p>

Deploy

<p> <a href="https://workers.cloudflare.com/"><img src="https://img.shields.io/badge/Cloudflare_Workers-f38020?style=for-the-badge&logo=cloudflare&logoColor=202024" alt="Cloudflare Workers" /></a> </p>

Ferramentas

<p> <a href="https://git-scm.com/"><img src="https://img.shields.io/badge/Git-f1f1e9?style=for-the-badge&logo=git" alt="Git" /></a> <a href="https://www.npmjs.com/"><img src="https://img.shields.io/badge/npm-cb3837?style=for-the-badge&logo=npm&logoColor=white" alt="npm" /></a> <a href="https://developers.cloudflare.com/workers/wrangler/"><img src="https://img.shields.io/badge/Wrangler-f38020?style=for-the-badge&logo=cloudflare&logoColor=202024" alt="Wrangler" /></a> </p>

* Veja o arquivo <kbd>package.json</kbd> 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

Variável	Obrigatória?	Uso
DESPEZZAS_TOKEN	Opcional	Token bearer manual copiado de uma sessão web.
DESPEZZAS_EMAIL	Opcional	Login por e-mail/senha.
DESPEZZAS_PASSWORD	Opcional	Login por e-mail/senha.
DESPEZZAS_FIREBASE_API_KEY	Para e-mail/senha	Chave pública do Firebase Web usada para troca e refresh de token. Veja como obtê-la no .env.example.
DESPEZZAS_SESSION_FILE	Opcional	Caminho de sessão persistida; use none para desativar.
MCP_TRANSPORT	Opcional	stdio ou http; padrão stdio.
HOST / PORT	Opcional	Bind do servidor HTTP; padrão 127.0.0.1:8787.
MCP_PUBLIC_BASE_URL	Produção/OAuth	URL pública HTTPS para metadados OAuth.
MCP_OAUTH_TOKEN_SECRET	Recomendado	Assinatura estável dos tokens OAuth MCP.
MCP_OWNER_AUTH_CODE	Deploy privado	Código de proprietário para autorizações de conta única.
SESSION_ENCRYPTION_KEY	Cloudflare multiusuário	Criptografia de sessões no Workers KV.

🔐 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.

Etapa	Origem	Destino	Resultado
1	Usuário	/login do MCP	Envia e-mail e senha para autorização local.
2	MCP	API Despezzas	Troca credenciais por firebase_token.
3	MCP	Firebase	Troca firebase_token por idToken e refreshToken.
4	MCP	Cliente MCP/ChatGPT	Entrega um token OAuth MCP opaco.

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.

<details> <summary>Detalhes de descoberta OAuth e links oficiais</summary>

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

</details>

☁️ Deploy remoto

Caminho suportado para deploy remoto: Cloudflare Workers.

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

Provedor	Melhor para	Arquivos	Observação
Cloudflare Workers	MCP remoto com ChatGPT	wrangler.jsonc, src/cloudflare.ts	Caminho de deploy mantido no projeto.

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.

<!-- ===== FOOTER ===== -->

---

<p align="center"> Feito por <a href="https://www.guipm.dev/">@guipm.dev</a>. </p>

<p align="center"> <a href="#top"> <b>↑ Voltar ao topo ↑</b> </a> </p>