Despezzas MCP
Unofficial MCP server for reading and managing a single Despezzas financial account (37 tools claimed; 35 exposed in the schema), with all writes gated behind confirm=true.
Diagnostics & profile: check auth/version (
despezzas_status), read the authenticated profile, list profiles, switch the active profile, and read personal visibility preferences.Profiles (shared): create PJ/family/investments profiles, edit access and invites, delete, or leave a profile you're a member of.
Accounts: list accounts, list banks/logos, and create, edit, or delete manual accounts (amounts in integer cents).
Credit cards: list cards and create, edit, or delete manual cards (limit, closing/expiring dates, unlimited flag).
Categories: list default and user categories and subcategories.
Transactions (read): search with filters (dates, accounts, cards, categories, paid/expense, amount, paging), fetch a specific transaction, get a daily overview, and get a finance summary.
Transactions (write): create, update (with
THIS/THIS_AND_NEXT/ALLscope), batch-update up to 50, duplicate, toggle paid, and delete — plusprepare_*tools that build and validate changes without calling the API.Transfers: create transfers between accounts, with both connected legs handled on deletion.
Export: count/inspect transaction fields over a date range or call the export endpoint.
Raw API escape hatch:
despezzas_raw_apifor/vN/GET paths; non-GET methods requireallow_destructive=trueandconfirm=true.
Notes: monetary values are integer cents and dates are YYYY-MM-DD; every write requires confirm=true, sessions are in-memory only, each deployment is bound to one account, and it uses unofficial/undocumented endpoints. Also, the schema contradicts the README in places: available_limit_cents appears in the create/update credit-card schemas despite being documented as read-only, there is no despezzas_prepare_batch_update_transactions tool, and the schema lists 35 tools rather than the claimed 37.
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.
Despezzas MCP
MCP não oficial para consultar e administrar dados financeiros do Despezzas.
Conecte seu cliente MCP à sua conta, consulte informações e prepare alterações antes de executá-las. Este repositório reúne o servidor, os testes e as orientações de uso.
📍 Visão geral
O servidor expõe 37 ferramentas MCP para perfis, contas, cartões, categorias, transações, transferências, resumos e diagnósticos. Foi construído a partir de endpoints observados no aplicativo web e não é afiliado ao Despezzas.
O uso local é via stdio. A implantação remota mantida é no Prefect Horizon, com OAuth gerenciado pela plataforma. Cada fork e implantação representam uma única conta Despezzas; as sessões ficam apenas em memória.
Este servidor acessa finanças reais. Toda escrita exigeconfirm: true; revise os dados antes de confirmar. Nunca inclua .env, tokens, senhas, sessões, HARs, respostas da API ou exportações financeiras no repositório. Nunca envie a senha do Despezzas como argumento de ferramenta.
Cada deployment é vinculado a uma única conta. Faça fork do repositório, publique seu próprio deployment no Prefect Horizon e configure somente os seus secrets. Não use nem compartilhe o deployment de outra pessoa: ele acessa os dados financeiros definidos nos secrets daquele servidor.
Related MCP server: monarch-mcp-server
✨ Recursos
O que você quer fazer? | Ferramentas e orientações |
Consultar perfis, contas e cartões |
|
Buscar transações e consultar resumos |
|
Preparar uma alteração sem executá-la |
|
Entender as regras de escrita | |
Implantar e conectar um cliente | |
Consultar o catálogo e o código |
Valores monetários usam centavos inteiros (12345 = R$ 123,45); datas usam YYYY-MM-DD. As ferramentas publicam esquemas de entrada e saída e anotações MCP explícitas para distinguir leituras, criações, atualizações, exclusões e operações não idempotentes.
Criações e edições de transação são relidas e validadas após a escrita. Campo omitido é preservado; null explícito limpa campos anuláveis. A API bruta é um recurso avançado: métodos diferentes de GET exigem allow_destructive: true e confirm: true.
A criação compara o estado anterior e confere quantidade, datas, parcelas e campos persistidos. A edição lê e mescla os dados antes do
PUT.A busca oferece
offset, cursor opaco e ordenação estável.despezzas_get_transactionlocaliza um ID fora do mês atual.despezzas_statusinforma a versão pública do servidor.Em séries, a prévia mostra o pagamento de cada ocorrência: somente a primeira pode iniciar paga; as futuras ficam pendentes.
Recorrências mensais iniciadas nos dias 29, 30 ou 31 são bloqueadas devido ao comportamento de datas da API.
Escritas parciais são informadas explicitamente; não são repetidas automaticamente nem têm reversão automática. Releia o estado antes de preparar apenas as alterações restantes.
Exclusões de transferência tratam as duas pontas conectadas, inclusive relações que usam o ID bruto da API.
available_limit_centsé somente leitura e não pertence aos esquemas de criação ou edição de cartão. Consulte esse valor pela lista de cartões.
O contrato de escritas detalha validação, persistência parcial, recorrências e segurança. Os registros da API documentam os comportamentos observados.
🎨 Prévia
Verificar a conexão
Após configurar o servidor, selecione despezzas_status no Inspector ou no cliente MCP. A ferramenta informa a versão e o estado de autenticação, sem alterar dados financeiros.
{
"name": "despezzas_status",
"arguments": {}
}O exemplo mostra apenas o nome da ferramenta e os argumentos. Não é uma resposta real, um arquivo de configuração de cliente nem uma comprovação de implantação ativa.
Preparar antes de confirmar
Consulte os recursos e IDs atuais.
Use uma ferramenta
despezzas_prepare_*e revise a prévia.Execute a ferramenta de escrita somente depois de revisar os argumentos e enviar
confirm: true.
As prévias podem consultar dados para montar a comparação, mas não escrevem. Para exemplos de pedidos em linguagem natural, veja como conectar um cliente MCP.
🛠️ Ferramentas
Servidor
Python e FastMCP compõem o servidor. HTTPX faz as requisições à API; Pydantic define e valida os modelos. As dependências e seus intervalos de versão estão em pyproject.toml.
Desenvolvimento e implantação
Ferramenta | Uso no projeto |
uv | Instalar dependências e executar comandos |
pytest | Verificar o catálogo e os comportamentos do servidor |
Ruff | Formatar e analisar o código |
Prefect Horizon | Implantar o MCP remoto e gerenciar sua autenticação OAuth |
Os badges identificam tecnologias e condições documentadas. Não comprovam versões instaladas, testes aprovados ou disponibilidade do serviço.
🚀 Primeiros passos
Executar localmente
Você precisa de Python 3.11 ou superior, uv e acesso a uma conta Despezzas. Obtenha o código:
git clone https://github.com/guipmilek/despezzas-mcp.git
cd despezzas-mcp
uv sync --extra dev
if (-not (Test-Path -LiteralPath .env)) { Copy-Item .env.example .env }Edite o arquivo .env no seu computador. Configure uma destas opções:
DESPEZZAS_TOKEN; ouDESPEZZAS_EMAIL,DESPEZZAS_PASSWORDeDESPEZZAS_FIREBASE_API_KEY.
Se .env já existir, preserve sua configuração. Não o inclua no controle de versão.
uv run --env-file .env despezzas-mcpEsse comando inicia o servidor via stdio; o cliente MCP precisa iniciá-lo e se comunicar com ele por esse transporte. A sessão Firebase fica em memória. Após uma nova inicialização sem sessão, o servidor autentica novamente com as credenciais configuradas.
Depois de publicar seu próprio fork e deployment, use estes metadados ao adicionar o MCP no ChatGPT. Nunca use a URL de outra pessoa:
Campo | Valor |
Nome |
|
Descrição |
|
URL |
|
Autenticação | OAuth |
Imagem |
|
Ative o modo de desenvolvedor em Configurações → Segurança e login, abra Plugins, selecione +, preencha os campos acima e conclua a autenticação. Veja o guia de conexão com o ChatGPT para o passo a passo, os testes de validação e a atualização do catálogo.
Faça fork deste repositório.
Entre em horizon.prefect.io com GitHub e escolha o fork.
Use o ponto de entrada
src/despezzas_mcp/server.py:mcp.Cadastre as credenciais do Despezzas nos secrets do Horizon.
Habilite Authentication.
Faça a implantação e teste primeiro
despezzas_statusno Inspector.Conecte o cliente MCP à URL
/mcpfornecida pelo Horizon, com OAuth.
O endpoint terá formato semelhante a https://seu-servidor.fastmcp.app/mcp. Use uma implantação por conta; não compartilhe a implantação entre pessoas nem as credenciais. Conceder acesso ao MCP permite acessar a conta financeira configurada, mesmo sem revelar os secrets.
Guia de implantação · Conexão de clientes MCP
uv sync --extra dev
uv run ruff format --check .
uv run ruff check .
uv run pytest
uv run fastmcp inspect src/despezzas_mcp/server.py:mcpPara aplicar a formatação, use uv run ruff format ..
O teste de conexão abaixo é opcional, somente leitura e acessa endpoints reais. Execute-o apenas quando precisar verificar a integração e tiver configurado as credenciais:
uv run --env-file .env python scripts/smoke_readonly.pyPara inspecionar um HAR com dados mascarados:
uv run python scripts/inspect_har.py C:\caminho\captura.harNão publique a captura original. Consulte como contribuir e as instruções para agentes antes de alterar contratos ou arquitetura.
O endpoint oficial documentado pelo projeto é https://api.despezzas.com/mcp. Para comparar apenas metadados, autentique pelo navegador e liste os catálogos:
uv run fastmcp list https://api.despezzas.com/mcp --auth oauth --json
uv run fastmcp list src/despezzas_mcp/server.py --jsonNão salve argumentos, resultados de ferramentas ou dados financeiros. Metas, faturas e investimentos dependem de endpoints autenticados comprovados e documentados; não são capacidades declaradas deste servidor. Veja a matriz competitiva datada.
📄 Condições de uso
O projeto declara a licença MIT. A integração não é oficial e usa endpoints não documentados, que podem mudar.
A licença não cria vínculo com o Despezzas nem garante disponibilidade do serviço externo. Você continua responsável por revisar e autorizar operações na sua conta. Consulte as orientações de segurança e o contrato de escritas.
👏 Créditos
Autoria: Guilherme Milek, conforme pyproject.toml e LICENSE.
Desenvolvimento: majoritariamente assistido por IA, com revisão humana.
Símbolo: arquivo existente do projeto, preservado em assets/despezzas-mcp.png. A capa apenas o incorpora; não substitui o original.
Estrutura e navegação do README: adaptação do padrão reutilizável desenvolvido por Guilherme; os ícones funcionais locais são autorais.
Ícones funcionais: SVGs locais autorais para ações, estados, Python e FastMCP; não são logotipos oficiais das ferramentas.
Bandeiras: Twemoji, Twitter, Inc. e demais colaboradores; CC BY 4.0, sem alterações nos desenhos.
Contribuir · Orientações de segurança · Registro desta adaptação
Available Tools
35 toolsdespezzas_batch_update_transactionsEditar Transações em LoteADestructiveIdempotent
Pré-visualiza ou edita até 50 transações. Exige confirm=true para escrever.
Inputs: updates (required), confirm, stop_on_error. Returns: object
despezzas_create_accountCriar Conta ManualC
Cria conta manual. Exige confirm=true.
Inputs: logo (required), name (required), confirm, include_total_balance, +1 more. Returns: result
despezzas_create_credit_cardCriar Cartão de CréditoB
Cria cartão manual. Exige confirm=true.
Inputs: name (required), logo, confirm, account_id, +5 more. Returns: result
despezzas_create_profileCriar Perfil CompartilhadoB
Cria um perfil extra PJ, família ou investimentos. Exige confirm=true.
Inputs: name (required), type (required), confirm, invites. Returns: result
despezzas_create_transactionCriar TransaçãoA
Cria transação. Exige confirm=true e recomenda prepare primeiro.
Inputs: date (required), title (required), amount_cents (required), kind, +12 more. Returns: result
despezzas_create_transferCriar TransferênciaB
Cria transferência entre contas. Exige confirm=true.
Inputs: date (required), amount_cents (required), sent_account_id (required), received_account_id (required), +4 more. Returns: result
despezzas_delete_accountExcluir ContaCDestructiveIdempotent
Exclui conta. Exige confirm=true.
Inputs: id (required), confirm. Returns: object
despezzas_delete_credit_cardExcluir Cartão de CréditoADestructiveIdempotent
Exclui cartão. Exige confirm=true.
Inputs: id (required), confirm. Returns: object
despezzas_delete_profileExcluir Perfil CompartilhadoBDestructiveIdempotent
Exclui um perfil compartilhado próprio. Exige confirm=true.
Inputs: id (required), confirm. Returns: object
despezzas_delete_transactionExcluir TransaçãoADestructiveIdempotent
Exclui transação. Exige confirm=true.
Inputs: id (required), scope, confirm. Returns: object
despezzas_duplicate_transactionDuplicar TransaçãoB
Duplica transação. Exige confirm=true.
Inputs: id (required), confirm. Returns: result
despezzas_export_transactionsExportar TransaçõesCRead-onlyIdempotent
Conta e inspeciona campos; count_only=false chama o endpoint de exportação.
Inputs: date_end (required), date_start (required), count_only, account_ids, +3 more. Returns: object
despezzas_finance_summaryResumo FinanceiroARead-onlyIdempotent
Resume receitas, despesas, pagamentos e categorias; padrão mês atual.
Inputs: limit, date_end, date_start, account_type, +1 more. Returns: object
despezzas_leave_profileSair de Perfil CompartilhadoBDestructiveIdempotent
Sai de um perfil em que a conta é membro. Exige confirm=true.
Inputs: profile_id (required), confirm. Returns: result
despezzas_list_accountsListar ContasARead-onlyIdempotent
Lista contas e o contexto do perfil ativo.
Inputs: no named parameters. Returns: object
despezzas_list_banksListar Bancos/Logos de ContaARead-onlyIdempotent
Lista opções de bancos e logos usadas em contas manuais.
Inputs: no named parameters. Returns: result
despezzas_list_categoriesListar CategoriasBRead-onlyIdempotent
Lista categorias padrão e do usuário.
Inputs: include_user. Returns: result
despezzas_list_credit_cardsListar Cartões de CréditoARead-onlyIdempotent
Lista cartões e o contexto do perfil ativo.
Inputs: no named parameters. Returns: object
despezzas_list_profilesListar Perfis do DespezzasARead-onlyIdempotent
Lista perfis de proprietário e membro e informa o perfil ativo.
Inputs: no named parameters. Returns: object
despezzas_list_subcategoriesListar SubcategoriasBRead-onlyIdempotent
Lista subcategorias padrão e do usuário.
Inputs: include_user. Returns: result
despezzas_personal_configObter Configuração PessoalBRead-onlyIdempotent
Busca preferências de visibilidade financeira.
Inputs: no named parameters. Returns: result
despezzas_prepare_create_transactionPreparar Criação de TransaçãoCRead-onlyIdempotent
Monta e valida uma transação sem chamar a API.
Inputs: date (required), title (required), amount_cents (required), kind, +11 more. Returns: object
despezzas_prepare_delete_transactionPreparar Exclusão de TransaçãoCRead-onlyIdempotent
Mostra alvo e escopo sem excluir.
Inputs: id (required), scope. Returns: object
despezzas_prepare_update_transactionPreparar Edição de TransaçãoBRead-onlyIdempotent
Monta e valida uma edição sem chamar a API.
Inputs: id (required), date, kind, paid, +9 more. Returns: object
despezzas_profileObter Perfil do DespezzasARead-onlyIdempotent
Busca o perfil autenticado. Campos sensíveis são mascarados.
Inputs: no named parameters. Returns: result
despezzas_raw_apiChamada Bruta à API DespezzasBDestructive
Executa GET bruto; outros métodos exigem allow_destructive=true e confirm=true.
Inputs: path (required), body, query, method, +2 more. Returns: result
despezzas_search_transactionsBuscar TransaçõesCRead-onlyIdempotent
Lista transações filtradas; por padrão usa o mês atual e contas bancárias.
Inputs: limit, order, search, is_paid, +11 more. Returns: object
despezzas_statusStatus do Despezzas MCPARead-onlyIdempotent
Verifica se o servidor tem credenciais ou token do Despezzas.
Inputs: no named parameters. Returns: object
despezzas_switch_profileTrocar Perfil AtivoAIdempotent
Troca o perfil ativo. Exige confirm=true.
Inputs: profile_id (required), confirm. Returns: object
despezzas_toggle_transaction_paidAlternar Pagamento da TransaçãoCDestructive
Alterna pagamento na data. Exige confirm=true.
Inputs: id (required), date, confirm. Returns: result
despezzas_transaction_overviewVisão Geral de TransaçõesCRead-onlyIdempotent
Obtém totais e saldos para uma data.
Inputs: date. Returns: result
despezzas_update_accountEditar ContaCDestructiveIdempotent
Edita conta manual. Exige confirm=true.
Inputs: id (required), logo, name, confirm, +2 more. Returns: result
despezzas_update_credit_cardEditar Cartão de CréditoCDestructiveIdempotent
Edita cartão manual. Exige confirm=true.
Inputs: id (required), logo, name, confirm, +6 more. Returns: result
despezzas_update_profile_accessEditar Perfil CompartilhadoCDestructiveIdempotent
Edita perfil compartilhado; invites substitui a lista atual. Exige confirm=true.
Inputs: id (required), name, type, confirm, +1 more. Returns: result
despezzas_update_transactionEditar TransaçãoCDestructiveIdempotent
Edita transação. Exige confirm=true.
Inputs: id (required), date, kind, paid, +10 more. Returns: result
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 name and description, covering different resources (accounts, profiles, credit cards, transactions) and actions (list, create, update, delete, search, etc.) with no overlap.
All tools follow a consistent 'despezzas_verb_noun' pattern in snake_case, making the intended action and resource clear. Even nuanced operations like 'prepare_create_transaction' adhere to this convention.
With 35 tools, the set is on the higher side but still reasonable for a comprehensive personal finance API that includes profiles, accounts, credit cards, transactions, and advanced operations like batch updates and exports.
The tool set covers full CRUD for accounts, credit cards, and transactions, plus search, finance summaries, transfers, exports, and duplicate/toggle operations. The presence of a 'raw_api' tool suggests possible edge cases not covered, but the main surface is thorough.
Maintenance
Related MCP Connectors
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
Query your real net worth, spending, transactions, budgets and portfolio from any MCP client.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceMCP Server to query from your Beancount ledger, or submit transaction.11MIT
- AlicenseBqualityAmaintenanceMCP Server for Monarch Money, utilizing an unofficial api.11433MIT
- AlicenseNot gradedqualityDmaintenanceA lightweight MCP server for tracking personal expenses, income, and budget summaries using SQLite.4Martin Birgmeier
- AlicenseAqualityCmaintenanceAn 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.35MIT