Skip to main content
Glama
Despezzas MCP

Despezzas MCP

by guipmilek

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

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

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

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.

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

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:

  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.


Available Tools

35 tools
despezzas_batch_update_transactionsEditar Transações em LoteA
Destructive

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 ManualB
Destructive

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éditoC
Destructive

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 CompartilhadoA
Destructive

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çãoA
Destructive

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ênciaB
Destructive

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 ContaA
Destructive

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éditoA
Destructive

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 CompartilhadoA
Destructive

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çãoA
Destructive

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çãoC
Destructive

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 CompartilhadoA
Destructive

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çãoA
Read-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çãoA
Read-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çãoA
Read-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 DespezzasA
Destructive

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 AtivoA
Destructive

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çãoB
Destructive

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 ContaB
Destructive

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éditoA
Destructive

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 CompartilhadoB
Destructive

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çãoA
Destructive

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

    A3.7/5.0

    Scored across 35 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      An MCP server that lets AI assistants interact with your Lunchmoney data, enabling natural language queries about transactions, budgets, and spending patterns.
      4
      22 npm
      29
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      An 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.
      -
    • A
      license
      A
      quality
      B
      maintenance
      An 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.
      59
      934 npm
      115
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      A 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 npm
      4
      MIT