Skip to main content
Glama
Despezzas MCP

Despezzas MCP

by guipmilek

Despezzas MCP — símbolo do projeto e nome sobre fundo azul-claro

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.

IMPORTANT

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

despezzas_list_profiles, despezzas_list_accounts, despezzas_list_credit_cards

Buscar transações e consultar resumos

despezzas_get_transaction, despezzas_search_transactions, despezzas_finance_summary

Preparar uma alteração sem executá-la

despezzas_prepare_create_transaction, despezzas_prepare_update_transaction, despezzas_prepare_batch_update_transactions

Entender as regras de escrita

Contrato de escritas · Segurança

Implantar e conectar um cliente

Prefect Horizon · Conexão de clientes MCP

Consultar o catálogo e o código

Catálogo em llms.txt · Ferramentas do servidor

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_transaction localiza um ID fora do mês atual.

  • despezzas_status informa 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

  1. Consulte os recursos e IDs atuais.

  2. Use uma ferramenta despezzas_prepare_* e revise a prévia.

  3. 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; ou

  • DESPEZZAS_EMAIL, DESPEZZAS_PASSWORD e DESPEZZAS_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-mcp

Esse 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

Despezzas

Descrição

Consulte e gerencie perfis, contas, cartões, transações, transferências e resumos financeiros do Despezzas, com confirmação obrigatória antes de alterações.

URL

https://seu-servidor.fastmcp.app/mcp — substitua pela URL do seu deployment

Autenticação

OAuth

Imagem

assets/despezzas-mcp.png — PNG quadrado, 512 × 512, menor que 100 KB

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.

  1. Faça fork deste repositório.

  2. Entre em horizon.prefect.io com GitHub e escolha o fork.

  3. Use o ponto de entrada src/despezzas_mcp/server.py:mcp.

  4. Cadastre as credenciais do Despezzas nos secrets do Horizon.

  5. Habilite Authentication.

  6. Faça a implantação e teste primeiro despezzas_status no Inspector.

  7. Conecte o cliente MCP à URL /mcp fornecida 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:mcp

Para 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.py

Para inspecionar um HAR com dados mascarados:

uv run python scripts/inspect_har.py C:\caminho\captura.har

Nã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 --json

Nã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 tools
despezzas_batch_update_transactionsEditar Transações em LoteA
DestructiveIdempotent

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 ContaC
DestructiveIdempotent

Exclui conta. Exige confirm=true.

Inputs: id (required), confirm. Returns: object

despezzas_delete_credit_cardExcluir Cartão de CréditoA
DestructiveIdempotent

Exclui cartão. Exige confirm=true.

Inputs: id (required), confirm. Returns: object

despezzas_delete_profileExcluir Perfil CompartilhadoB
DestructiveIdempotent

Exclui um perfil compartilhado próprio. Exige confirm=true.

Inputs: id (required), confirm. Returns: object

despezzas_delete_transactionExcluir TransaçãoA
DestructiveIdempotent

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çõesC
Read-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 FinanceiroA
Read-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 CompartilhadoB
DestructiveIdempotent

Sai de um perfil em que a conta é membro. Exige confirm=true.

Inputs: profile_id (required), confirm. Returns: result

despezzas_list_accountsListar ContasA
Read-onlyIdempotent

Lista contas e o contexto do perfil ativo.

Inputs: no named parameters. Returns: object

despezzas_list_banksListar Bancos/Logos de ContaA
Read-onlyIdempotent

Lista opções de bancos e logos usadas em contas manuais.

Inputs: no named parameters. Returns: result

despezzas_list_categoriesListar CategoriasB
Read-onlyIdempotent

Lista categorias padrão e do usuário.

Inputs: include_user. Returns: result

despezzas_list_credit_cardsListar Cartões de CréditoA
Read-onlyIdempotent

Lista cartões e o contexto do perfil ativo.

Inputs: no named parameters. Returns: object

despezzas_list_profilesListar Perfis do DespezzasA
Read-onlyIdempotent

Lista perfis de proprietário e membro e informa o perfil ativo.

Inputs: no named parameters. Returns: object

despezzas_list_subcategoriesListar SubcategoriasB
Read-onlyIdempotent

Lista subcategorias padrão e do usuário.

Inputs: include_user. Returns: result

despezzas_personal_configObter Configuração PessoalB
Read-onlyIdempotent

Busca preferências de visibilidade financeira.

Inputs: no named parameters. Returns: result

despezzas_prepare_create_transactionPreparar Criação de TransaçãoC
Read-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çãoC
Read-onlyIdempotent

Mostra alvo e escopo sem excluir.

Inputs: id (required), scope. Returns: object

despezzas_prepare_update_transactionPreparar Edição de TransaçãoB
Read-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 DespezzasA
Read-onlyIdempotent

Busca o perfil autenticado. Campos sensíveis são mascarados.

Inputs: no named parameters. Returns: result

despezzas_raw_apiChamada Bruta à API DespezzasB
Destructive

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çõesC
Read-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 MCPA
Read-onlyIdempotent

Verifica se o servidor tem credenciais ou token do Despezzas.

Inputs: no named parameters. Returns: object

despezzas_switch_profileTrocar Perfil AtivoA
Idempotent

Troca o perfil ativo. Exige confirm=true.

Inputs: profile_id (required), confirm. Returns: object

despezzas_toggle_transaction_paidAlternar Pagamento da TransaçãoC
Destructive

Alterna pagamento na data. Exige confirm=true.

Inputs: id (required), date, confirm. Returns: result

despezzas_transaction_overviewVisão Geral de TransaçõesC
Read-onlyIdempotent

Obtém totais e saldos para uma data.

Inputs: date. Returns: result

despezzas_update_accountEditar ContaC
DestructiveIdempotent

Edita conta manual. Exige confirm=true.

Inputs: id (required), logo, name, confirm, +2 more. Returns: result

despezzas_update_credit_cardEditar Cartão de CréditoC
DestructiveIdempotent

Edita cartão manual. Exige confirm=true.

Inputs: id (required), logo, name, confirm, +6 more. Returns: result

despezzas_update_profile_accessEditar Perfil CompartilhadoC
DestructiveIdempotent

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

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

    B3.3/5.0

    Scored across 35 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count3/5

    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.

    Completeness4/5

    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

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP Server to query from your Beancount ledger, or submit transaction.
      11
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      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.
      35
      MIT