Despezzas MCP

• Visão geral

• Início rápido

• Ferramentas e segurança

• Conectar ao ChatGPT

• Deploy no Prefect Horizon

• Desenvolvimento

• Comparação com o MCP oficial

Visão geral

Este projeto expõe 37 ferramentas MCP para perfis, contas, cartões, categorias, transações, transferências, resumos e diagnósticos do Despezzas. É uma integração open-source construída sobre endpoints observados no aplicativo web; não é afiliada ao Despezzas.

O catálogo publica schemas de entrada e saída e annotations MCP completas. As annotations distinguem leitura, criação, atualização, exclusão e operações não idempotentes para clientes como ChatGPT planejarem chamadas com segurança.

Related MCP server: monarch-mcp-server

Início rápido

Instale o uv e execute:

uv sync --extra dev
Copy-Item .env.example .env
uv run --env-file .env despezzas-mcp

Para clientes locais, o comando acima usa stdio. Configure uma destas opções:

• DESPEZZAS_TOKEN; ou

• DESPEZZAS_EMAIL, DESPEZZAS_PASSWORD e DESPEZZAS_FIREBASE_API_KEY.

A sessão Firebase fica apenas em memória. Após cold start, o servidor autentica novamente usando os secrets do deploy.

Ferramentas e segurança

Os grupos principais são:

Valores monetários usam centavos inteiros (12345 = R$123,45) e datas usam YYYY-MM-DD. Toda escrita exige confirm: true; despezzas_raw_api também exige allow_destructive: true para métodos diferentes de GET. Criações e edições de transação são relidas e validadas após a escrita. A criação compara o snapshot anterior e confirma quantidade, datas, parcelas e campos persistidos; a edição faz merge antes do PUT. Campo omitido é preservado; null explícito limpa campos anuláveis. A busca oferece offset, cursor opaco e ordenação estável, e despezzas_get_transaction localiza um ID fora do mês atual. despezzas_status informa a versão pública do servidor. Em séries, o preview mostra o estado de pagamento de cada ocorrência: somente a primeira pode iniciar paga, enquanto as futuras permanecem pendentes. Exclusões de transferência tratam as duas pontas conectadas, mesmo quando a API relaciona o ID bruto em vez do ID interno. available_limit_cents é somente leitura e não pertence aos schemas de criação ou edição de cartão. Consulte o contrato de escritas antes de habilitar mutações.

Conectar ao ChatGPT

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:

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.

Deploy no Prefect Horizon

1. Faça fork deste repositório.

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

3. Use o entrypoint src/despezzas_mcp/server.py:mcp.

4. Cadastre os secrets do Despezzas.

5. Habilite Authentication no Horizon.

6. Faça deploy e teste as ferramentas no Inspector.

O endpoint será semelhante a https://seu-servidor.fastmcp.app/mcp. Cada fork contém as credenciais de uma única conta; não compartilhe o deployment entre pessoas. Consulte docs/deployment.md.

Desenvolvimento

uv sync --extra dev
uv run ruff format .
uv run ruff check .
uv run pytest
uv run fastmcp inspect src/despezzas_mcp/server.py:mcp

Smoke test opcional e somente leitura:

uv run --env-file .env python scripts/smoke_readonly.py

Inspeção mascarada de HAR:

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

Comparação com o MCP oficial

O MCP oficial está em https://api.despezzas.com/mcp. Para comparar apenas metadados, autentique via 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 só devem ser adicionados depois de endpoints autenticados serem comprovados e documentados. Veja a matriz competitiva datada.