Despezzas MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Despezzas MCP list my accounts"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
📍 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.
Integração não oficial. Endpoints e fluxos de login podem mudar sem aviso.
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.
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.
Item | Valor |
Status | MVP funcional para uso pessoal |
API | Integração não oficial com endpoints do Despezzas |
Runtime | Node.js |
Transportes |
|
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 devDepois 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_transactionoudespezzas_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 |
| Parcial | Trocar/criar/excluir perfil exige |
Contas e cartões |
| Parcial | Escritas validam IDs e confirmação. |
Categorias |
| Não | Use antes de criar/editar transações. |
Transações |
| Parcial | Criação exige destino, categoria ou |
Pré-visualização |
| Não | Caminho recomendado antes de qualquer escrita. |
Diagnóstico |
| 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 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:readonlynpm 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 |
| Opcional | Token bearer manual copiado de uma sessão web. |
| Opcional | Login por e-mail/senha. |
| Opcional | Login por e-mail/senha. |
| Para e-mail/senha | Chave pública do Firebase Web usada para troca e refresh de token. Veja como obtê-la no .env.example. |
| Opcional | Caminho de sessão persistida; use |
| Opcional |
|
| Opcional | Bind do servidor HTTP; padrão |
| Produção/OAuth | URL pública HTTPS para metadados OAuth. |
| Recomendado | Assinatura estável dos tokens OAuth MCP. |
| Deploy privado | Código de proprietário para autorizações de conta única. |
| 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_PASSWORDeDESPEZZAS_FIREBASE_API_KEY(chave pública — veja .env.example) no.env.Copie o
DESPEZZAS_TOKENpelas 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/authcom e-mail/senha.Usa o
firebase_tokenretornado com Firebaseaccounts:signInWithCustomTokenusandoDESPEZZAS_FIREBASE_API_KEY(a chave pública do Firebase Web do Despezzas).Usa o
idTokendo Firebase comoAuthorization: Bearer ...emapi.despezzas.com.Salva o refresh token do Firebase em
%USERPROFILE%\.despezzas-mcp\session.jsonpor padrão.
Etapa | Origem | Destino | Resultado |
1 | Usuário |
| Envia e-mail e senha para autorização local. |
2 | MCP | API Despezzas | Troca credenciais por |
3 | MCP | Firebase | Troca |
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:httpVerificação de saúde:
Invoke-RestMethod http://127.0.0.1:8787/healthAbra a página local de autorização:
Start-Process http://127.0.0.1:8787/loginSe 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:cloudflareConfirme a URL pública do Worker:
Invoke-RestMethod https://despezzas-mcp.<sua-conta>.workers.dev/healthNo ChatGPT, use:
URL do servidor:
https://despezzas-mcp.<sua-conta>.workers.dev/mcpAutenticação:
OAuth
O servidor expõe os endpoints de descoberta esperados pelo ChatGPT:
GET /.well-known/oauth-protected-resourceGET /.well-known/oauth-authorization-serverPOST /oauth/registerGET|POST /oauth/authorizePOST /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:
☁️ 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 |
| Caminho de deploy mantido no projeto. |
Arquivos de deploy mantidos:
wrangler.jsoncesrc/cloudflare.tspara Cloudflare Workers.docs/cloudflare-workers.mdpara 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.harO 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: trueobrigatório para toda ferramenta de escrita/destrutiva.Atualize
llms.txt,AGENTS.mde os docs emdocs/quando mudar arquitetura, comandos, ferramentas MCP ou regras importantes para agentes.
📄 Licença
MIT. Veja LICENSE.
Available Tools
35 toolsdespezzas_batch_update_transactionsEditar Transações em LoteADestructive
Operação de escrita. Pré-visualiza e depois edita várias transações do Despezzas com uma chamada confirm:true. Exige confirm: true. Chame uma vez sem confirm para inspecionar os payloads; repita com confirm:true apenas depois de verificar cada id e payload.
Inputs: updates (required), confirm, stop_on_error. Returns: note, total, preview, results, +5 more
despezzas_create_accountCriar Conta ManualBDestructive
Operação de escrita. Cria uma conta manual no Despezzas. Exige confirm: true.
Inputs: logo (required), name (required), confirm, include_total_balance, +1 more. Returns: object
despezzas_create_credit_cardCriar Cartão de CréditoCDestructive
Operação de escrita. Cria um cartão de crédito manual no Despezzas. Exige confirm: true.
Inputs: name (required), logo, confirm, account_id, +5 more. Returns: object
despezzas_create_profileCriar Perfil CompartilhadoADestructive
Operação de escrita. Cria um dos três perfis extras do Despezzas (PJ, família ou investimentos). Exige confirm: true.
Inputs: name (required), type (required), confirm, invites. Returns: object
despezzas_create_transactionCriar TransaçãoADestructive
Operação de escrita. Cria uma transação real no Despezzas. Exige confirm: true. Use despezzas_prepare_create_transaction primeiro e nunca adivinhe IDs de conta/cartão/categoria.
Inputs: date (required), title (required), amount_cents (required), kind, +12 more. Returns: created, payload, transaction
despezzas_create_transferCriar TransferênciaBDestructive
Operação de escrita. Cria uma transferência entre duas contas do Despezzas. Exige confirm: true.
Inputs: date (required), amount_cents (required), sent_account_id (required), received_account_id (required), +4 more. Returns: object
despezzas_delete_accountExcluir ContaADestructive
Operação de escrita destrutiva. Exclui uma conta do Despezzas. Exige confirm: true.
Inputs: id (required), confirm. Returns: object
despezzas_delete_credit_cardExcluir Cartão de CréditoADestructive
Operação de escrita destrutiva. Exclui um cartão de crédito do Despezzas. Exige confirm: true.
Inputs: id (required), confirm. Returns: object
despezzas_delete_profileExcluir Perfil CompartilhadoADestructive
Operação de escrita destrutiva. Exclui um perfil compartilhado de sua propriedade. Exige confirm: true.
Inputs: id (required), confirm. Returns: object
despezzas_delete_transactionExcluir TransaçãoADestructive
Operação de escrita destrutiva. Exclui uma transação. Exige confirm: true. Use despezzas_prepare_delete_transaction primeiro.
Inputs: id (required), scope, confirm. Returns: object
despezzas_duplicate_transactionDuplicar TransaçãoCDestructive
Operação de escrita. Duplica uma transação do Despezzas. Exige confirm: true.
Inputs: id (required), confirm. Returns: object
despezzas_export_transactionsExportar TransaçõesC
Inspeciona/exporta transações do Despezzas em um intervalo de datas. Por padrão faz uma contagem segura com resumo de campos; defina count_only:false para chamar o endpoint de exportação.
Inputs: date_end (required), date_start (required), count_only, account_ids, +3 more. Returns: object
despezzas_finance_summaryResumo FinanceiroA
Resume receitas, despesas, totais pagos/não pagos e principais categorias em um intervalo de datas. Por padrão usa o mês atual.
Inputs: limit, date_end, date_start, account_type, +1 more. Returns: object
despezzas_leave_profileSair de Perfil CompartilhadoADestructive
Operação de escrita. Sai de um perfil compartilhado em que você é membro. Exige confirm: true.
Inputs: profile_id (required), confirm. Returns: object
despezzas_list_accountsListar ContasA
Lista contas bancárias/dinheiro do Despezzas. Use primeiro para descobrir IDs de conta para filtros de transação.
Inputs: no named parameters. Returns: object
despezzas_list_banksListar Bancos/Logos de ContaA
Lista opções de bancos/logos usadas ao criar contas manuais no Despezzas.
Inputs: no named parameters. Returns: object
despezzas_list_categoriesListar CategoriasA
Lista categorias padrão e, opcionalmente, categorias criadas pelo usuário no Despezzas.
Inputs: include_user. Returns: object
despezzas_list_credit_cardsListar Cartões de CréditoA
Lista cartões de crédito do Despezzas. Use para descobrir IDs de cartão para filtros de transação.
Inputs: no named parameters. Returns: object
despezzas_list_profilesListar Perfis do DespezzasA
Lista perfis Despezzas de proprietário e membro. Use antes de trocar o contexto de perfil ou gerenciar perfis compartilhados.
Inputs: no named parameters. Returns: object
despezzas_list_subcategoriesListar SubcategoriasB
Lista subcategorias padrão e, opcionalmente, subcategorias criadas pelo usuário no Despezzas. Use category_id no resultado para vinculá-las às categorias.
Inputs: include_user. Returns: object
despezzas_personal_configObter Configuração PessoalB
Busca preferências de visibilidade financeira, como inclusão de transferências, contas ou investimentos.
Inputs: no named parameters. Returns: object
despezzas_prepare_create_transactionPreparar Criação de TransaçãoARead-only
Auxiliar de pré-visualização. Monta e valida o payload de uma nova transação sem chamar o Despezzas. Use antes de despezzas_create_transaction.
Inputs: date (required), title (required), amount_cents (required), kind, +11 more. Returns: note, ready, issues, method, +2 more
despezzas_prepare_delete_transactionPreparar Exclusão de TransaçãoARead-only
Auxiliar de pré-visualização. Mostra o alvo e o escopo da exclusão sem excluir nada. Use antes de despezzas_delete_transaction.
Inputs: id (required), scope. Returns: object
despezzas_prepare_update_transactionPreparar Edição de TransaçãoARead-only
Auxiliar de pré-visualização. Monta e valida o payload para editar uma transação sem chamar o Despezzas. Use antes de despezzas_update_transaction.
Inputs: id (required), date, kind, paid, +9 more. Returns: id, note, ready, issues, +3 more
despezzas_profileObter Perfil do DespezzasA
Busca o perfil autenticado do Despezzas. Campos sensíveis são mascarados.
Inputs: no named parameters. Returns: object
despezzas_raw_apiChamada Bruta à API DespezzasADestructive
Saída de emergência para endpoints descobertos depois. Chamadas GET seguras são permitidas. POST/PUT/PATCH/DELETE exigem allow_destructive: true.
Inputs: path (required), body, query, method, +1 more. Returns: object
despezzas_search_transactionsBuscar TransaçõesB
Lista transações do Despezzas com filtros. Por padrão usa o mês atual e a visão de fluxo de caixa de contas bancárias. Valores retornam em centavos.
Inputs: limit, order, search, is_paid, +11 more. Returns: count, filters, warning, has_more, +4 more
despezzas_statusStatus do Despezzas MCPA
Verifica se o servidor MCP está configurado com um token do Despezzas.
Inputs: no named parameters. Returns: object
despezzas_switch_profileTrocar Perfil AtivoADestructive
Operação de escrita. Troca o perfil Despezzas ativo para chamadas futuras de contas, cartões e transações. Exige confirm: true.
Inputs: profile_id (required), confirm. Returns: object
despezzas_toggle_transaction_paidAlternar Pagamento da TransaçãoBDestructive
Operação de escrita. Alterna ou marca uma transação como paga em uma data. Exige confirm: true.
Inputs: id (required), date, confirm. Returns: object
despezzas_transaction_overviewVisão Geral de TransaçõesC
Obtém totais da visão geral do Despezzas e saldos de conta para uma data. Valores em centavos.
Inputs: date. Returns: object
despezzas_update_accountEditar ContaBDestructive
Operação de escrita. Edita uma conta manual do Despezzas. Exige confirm: true.
Inputs: id (required), logo, name, confirm, +2 more. Returns: object
despezzas_update_credit_cardEditar Cartão de CréditoADestructive
Operação de escrita. Edita um cartão de crédito manual do Despezzas. Exige confirm: true.
Inputs: id (required), logo, name, confirm, +6 more. Returns: object
despezzas_update_profile_accessEditar Perfil CompartilhadoBDestructive
Operação de escrita. Edita um perfil compartilhado. Se invites for informado, ele substitui a lista de convites/membros. Exige confirm: true.
Inputs: id (required), name, type, confirm, +1 more. Returns: object
despezzas_update_transactionEditar TransaçãoADestructive
Operação de escrita. Edita uma transação real no Despezzas. Exige confirm: true. Use despezzas_prepare_update_transaction primeiro.
Inputs: id (required), date, kind, paid, +10 more. Returns: id, payload, updated, transaction
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 35 tools
Every tool has a distinct and clear purpose. Operations like create, delete, list, and update are uniquely scoped to accounts, credit cards, transactions, and profiles. Auxiliary 'prepare' tools are clearly separated from actual write operations, preventing confusion.
All tools follow a strict 'despezzas_verb_noun' pattern with consistent verb choices (create, delete, list, update, prepare, etc.). There are no mixed conventions or irregular names, making it easy to predict tool names.
With 35 tools, the set is slightly large but still well-scoped for a comprehensive personal finance management system. Each tool covers a distinct operation, and the count is justified by the breadth of features (accounts, credit cards, transactions, profiles, etc.). Minimal redundancy.
The tool surface covers most CRUD operations for accounts, credit cards, transactions, and profiles, plus auxiliary features like search, export, and finance summary. Minor gaps exist (e.g., no explicit category creation/deletion), but core workflows are fully supported.
Related MCP Connectors
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
Read-only finance MCP server. Connects your banks, cards, payment apps, books and payroll into one ledger for your AI. Can't move money. Open source (AGPL-3.0), free during beta.
Query your real net worth, spending, transactions, budgets and portfolio from any MCP client.
Personal finance for AI agents — onboard, import statements, categorize & budget over MCP.
Related MCP Servers
- AlicenseBqualityDmaintenanceAn MCP server that lets AI assistants interact with your Lunchmoney data, enabling natural language queries about transactions, budgets, and spending patterns.422 npm29MIT
- FlicenseNot gradedqualityDmaintenanceAn MCP server that enables AI assistants to interact directly with Lunch Money's financial API, allowing users to query transactions, access budget information, and perform financial analysis through natural language.-
- AlicenseAqualityBmaintenanceAn MCP server implementation that provides programmatic access to personal finance data through LunchMoney's API, enabling AI assistants to manage transactions, budgets, categories, and assets.59934 npm115MIT
- AlicenseNot gradedqualityCmaintenanceA comprehensive MCP server that enables AI assistants to manage Lunch Money finances through 37 tools for transactions, budgets, and accounts. It supports both local stdio and remote HTTP transport modes with secure, encrypted credential storage.11 npm4MIT