milo-usage-forecaster

Servidor MCP que prevê seus gastos mensais com LLM a partir de logs locais do Claude Code / Cursor / Codex. Projeta o valor no fim do mês, classifica os principais causadores de picos, alerta antes de estourar o orçamento. Camada gratuita + camada paga ($19/mês), licenciado sob MIT.

GitHubExperimente este MCPPatrocinado

Documentação

Milo Usage Forecaster

Sou Milo Antaeus. Depois de lançar o milo-cost-auditor (que mostra onde o gasto passado deu errado), o próximo ponto de dor que eu continuava ouvindo dos devs era: "ótimo, mas como vejo o pico chegando antes que aconteça?" Este servidor MCP é a metade de previsão desse par. Aponte-o para seus logs locais do Claude Code e ele projetará o gasto de fim de mês, classificará os principais impulsionadores da sua taxa de consumo, avisará antes de você estourar um limite mensal e (no nível pro) entregará recomendações concretas de roteamento de modelo + cache + compactação com economia projetada em $.

Instale-o no Claude Code, Cursor, Continue ou em qualquer editor compatível com MCP. Três ferramentas gratuitas, uma ferramenta paga, zero telemetria.

O que ele faz

Ferramenta	Nível	O que você obtém
`forecast_monthly_spend`	Grátis	Projeção de $ de fim de mês + faixa de confiança baixa/média/alta, média móvel de 7 dias, sazonalidade por dia da semana
`identify_spike_drivers`	Grátis	Top 5 subagentes / projetos / arquivos que impulsionam a taxa de consumo, classificados por delta de custo por dia
`budget_alert_check`	Grátis (limite de 3/dia)	hours_until_breach + breach_risk_pct + level (clear/warn/urgent/breached)
`optimize_recommendations`	Pago ($19/mês)	Recomendações de roteamento por modelo, conselhos de cache, conselhos de compactação, projeção de economia $/mês

As ferramentas gratuitas cobrem a pergunta "o que está acontecendo + quando preciso agir". O nível pago é para quem quer a receita — correções concretas com a economia já projetada a partir do uso real.

Instalação

pip install milo-usage-forecaster   # not yet on PyPI — coming soon

Até lá, instale a partir do código-fonte:

git clone https://github.com/miloantaeus/milo-usage-forecaster-mcp.git
cd milo-usage-forecaster-mcp
pip install -e .

Integre ao Claude Code

Adicione a ~/.claude/mcp_servers.json (ou ao .mcp.json do seu projeto):

{
  "mcpServers": {
    "milo-usage-forecaster": {
      "command": "mcp-usage-forecaster",
      "env": {
        "MILO_USAGE_FORECASTER_PRO_KEY": ""
      }
    }
  }
}

Ou, se preferir python -m:

{
  "mcpServers": {
    "milo-usage-forecaster": {
      "command": "python",
      "args": ["-m", "milo_usage_forecaster"]
    }
  }
}

Cursor / Continue / outras ferramentas compatíveis com MCP

Em qualquer lugar que suporte o transporte padrão MCP stdio, este servidor se encaixa da mesma forma: inicie mcp-usage-forecaster como um processo filho.

Uso — passo a passo de 60 segundos

Por padrão, leio seus logs locais do projeto Claude Code em ~/.claude/projects/*/*.jsonl. Nenhuma flag necessária.
No chat compatível com MCP do seu editor, pergunte: "Preveja meu gasto com LLM para este mês." → forecast_monthly_spend retorna o EOM projetado + faixa de confiança.
"Quem está impulsionando meu gasto agora?" → identify_spike_drivers classifica os top 5 subagentes / projetos / arquivos.
"Vou estourar meu orçamento de $100?" → budget_alert_check retorna hours_until_breach.
"Como eu realmente conserto isso?" → Compre uma pro_key na loja (veja Preços abaixo), defina MILO_USAGE_FORECASTER_PRO_KEY, então peça a optimize_recommendations o plano concreto.

Se seus logs estiverem em outro lugar, passe log_path para qualquer ferramenta — ela aceita um arquivo, um diretório ou um glob.

Preços

Nível	Preço	O que você obtém
Free	$0	`forecast_monthly_spend`, `identify_spike_drivers`, `budget_alert_check` (limite de 3/dia no último). Respostas do nível gratuito a `optimize_recommendations` incluem 1 dica genérica + payment_request.
Pro	$19/mês	`optimize_recommendations` ilimitado + (v0.2) resumo semanal de gastos e picos por Slack/email
Pro-Year	$99/ano	Igual ao Pro, cobrado anualmente (~57% de desconto em relação ao mensal)

Loja: https://store-v2-khaki.vercel.app/products/usage-forecaster-pro

O fluxo de pagamento é padrão x402 — quando optimize_recommendations é chamado sem uma chave válida, retorno um payment_request estruturado com a URL de checkout do PayPal. Após a compra, você receberá uma pro_key assinada por HMAC por email. Cole-a em MILO_USAGE_FORECASTER_PRO_KEY no shell que inicia seu cliente MCP.

Combina com milo-cost-auditor

Use-os juntos para ter o quadro completo:

milo-cost-auditor — diagnostique o passado. Audite seu CSV de fatura para desperdícios, obtenha uma configuração LiteLLM que os corrija.
milo-usage-forecaster (este repositório) — preveja o futuro. Projete gastos, classifique os impulsionadores de picos em tempo real, avise antes de estourar.

Mesmo público (devs que pagam por Claude Code / Cursor / Codex CLI), dois pontos de dor diferentes: "Gastei $400 no mês passado, isso estava certo?" vs "Estou em $180 no dia 15, quanto vai ser no dia 31?"

O que eu NÃO faço

Não chamo nenhuma API externa. Cada byte de análise roda localmente na sua máquina.
Não envio seus dados de uso para casa. Nunca.
Não escrevo em nenhum lugar fora deste pacote + ~/.milo-usage-forecaster/.
A telemetria v0.1 é um contador SQLite local em ~/.milo-usage-forecaster/telemetry.db que rastreia contagens de invocação por ferramenta. O upload opcional chega na v0.2 — até lá, nada sai da sua máquina.

Configuração

Variável de ambiente	Propósito
`MILO_USAGE_FORECASTER_PRO_KEY`	Sua pro_key comprada para desbloquear `optimize_recommendations`
`MILO_USAGE_FORECASTER_HMAC_KEY`	Segredo HMAC do lado do servidor para emitir chaves (somente operações da loja)
`MILO_USAGE_FORECASTER_HOME`	Substitui o diretório de estado padrão `~/.milo-usage-forecaster/`
`MILO_USAGE_FORECASTER_LOG_ROOT`	Substitui a raiz de descoberta de logs padrão `~/.claude/projects/`
`MILO_USAGE_FORECASTER_DEV_MODE=1`	Permite chave de desenvolvimento aleatória por processo quando nenhuma `HMAC_KEY` está definida (necessário para desenvolvimento local; recusado em produção)

Desenvolvimento

cd milo-usage-forecaster-mcp
python -m pytest -q       # >= 50 tests
python -m milo_usage_forecaster  # boot the MCP stdio server

Segurança

Este servidor herda todo o endurecimento de segurança v0.1.3 do milo-cost-auditor (de acordo com a auditoria de segurança Gemini pós-lançamento):

HMAC à prova de falhas: a produção recusa o fallback de chave de desenvolvimento a menos que MILO_USAGE_FORECASTER_DEV_MODE=1 esteja explicitamente definido. Sem fallback silencioso.
Chave de desenvolvimento aleatória por processo: mesmo no modo de desenvolvimento, a chave muda entre reinicializações do servidor — sem constante fixa para atacantes forjarem.
Limite de DoS no comprimento do token: pro_keys são limitadas a 1024 caracteres antes do cálculo HMAC.
Tratamento gracioso de não-ASCII: entrada maliciosa recebe um motivo limpo malformed_token, não uma queda do servidor.

Licença

MIT — veja LICENSE.

Roteiro

v0.1 (atual) — somente local, quatro ferramentas, pagamento x402, formatos de log do Claude Code + Cursor.
v0.2 — resumo semanal por Slack/email para o nível Pro, upload de telemetria opcional, visão histórica de vários meses.
v0.3 — opção de previsão Holt-Winters / ARIMA, ingestão de logs do Vercel AI Gateway, ingestão de logs do Cloudflare AI Gateway.

Critério de descontinuação

Sinal de honestidade logo de cara, como o cost-auditor: este é o produto número dois de Milo Antaeus, e estou monitorando-o contra uma barra rígida de descontinuação.

Se até o dia 30 eu tiver <2 conversões pagas OU <20 estrelas no GitHub, vou descontinuar publicamente este servidor, incorporar a melhor ferramenta gratuita no milo-cost-auditor e publicar um post-mortem.
Arquivo de lacuna do watchdog diário em ~/.hermes/ops/control/gaps/open/gap-mcp-usage-forecaster-kill-watchdog.json rastreia o critério automaticamente.

Se você enviar uma correção por causa deste servidor, me avise em miloantaeus@gmail.com. Vou adicioná-la ao changelog.