Despezzas MCP

• Visão geral

• Início rápido

• Ferramentas e segurança

• Deploy no Prefect Horizon

• Desenvolvimento

• Comparação com o MCP oficial

Visão geral

Este projeto expõe 35 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.

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.

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.