MCP 服务器

Despezzas MCP

An unofficial MCP server that connects Despezzas financial data to MCP clients like ChatGPT, enabling listing accounts, cards, categories, searching transactions, and performing write operations with safety protections.

README

<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" />

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

Servidor MCP não oficial para conectar dados financeiros do Despezzas a clientes compatíveis com MCP, incluindo ChatGPT.

<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
🚀 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>

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

Pesquise/liste a conta, cartão, categoria, subcategoria ou transação alvo.
Chame despezzas_prepare_create_transaction, despezzas_prepare_update_transaction ou despezzas_prepare_delete_transaction.
Revise o payload retornado e os IDs de destino.
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

Deploy

Ferramentas

* 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:

Execute em modo HTTP e abra http://127.0.0.1:8787/login.
Defina DESPEZZAS_EMAIL, DESPEZZAS_PASSWORD e DESPEZZAS_FIREBASE_API_KEY (chave pública — veja .env.example) no .env.
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:

POST https://api.despezzas.com/v2/auth com e-mail/senha.
Usa o firebase_token retornado com Firebase accounts:signInWithCustomToken usando DESPEZZAS_FIREBASE_API_KEY (a chave pública do Firebase Web do Despezzas).
Usa o idToken do Firebase como Authorization: Bearer ... em api.despezzas.com.
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:

Faça deploy em Cloudflare Workers seguindo docs/cloudflare-workers.md.
```
npm run check:cloudflare
npm run deploy:cloudflare
```

Confirme a URL pública do Worker:

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

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:

</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:

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:

Leia CONTRIBUTING.md.
Rode npm run verify.
Não inclua credenciais, tokens, sessões, HARs não mascarados ou dados financeiros reais.
Mantenha confirm: true obrigatório para toda ferramenta de escrita/destrutiva.
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.

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

<a href="#top"> ↑ Voltar ao topo ↑ </a>