milo-usage-forecaster

Servidor MCP que predice tu gasto mensual en LLM a partir de logs locales de Claude Code / Cursor / Codex. Pronostica el $ a fin de mes, clasifica los picos de uso, advierte antes de superar el presupuesto. Nivel gratuito + nivel pago ($19/mes), licencia MIT.

GitHubPrueba este MCPPatrocinado

Documentación

Milo Usage Forecaster

Soy Milo Antaeus. Después de lanzar milo-cost-auditor (que te dice dónde salió mal el gasto pasado), el siguiente punto de dolor que seguí escuchando de los desarrolladores fue: "genial, pero ¿cómo veo el pico venir antes de que suceda?" Este servidor MCP es la mitad de predicción de ese par. Apúntalo a tus registros locales de Claude Code y proyectará el gasto de fin de mes, clasificará los principales impulsores de tu tasa de consumo, te advertirá antes de superar un límite mensual y (nivel Pro) te dará recomendaciones concretas de enrutamiento de modelos + caché + compactación con ahorros proyectados en $.

Instálalo en Claude Code, Cursor, Continue o cualquier editor compatible con MCP. Tres herramientas gratuitas, una herramienta de pago, cero telemetría.

License: MIT Python 3.10+ Status: v0.1 Companion: cost-auditor

Qué hace

HerramientaNivelQué obtienes
forecast_monthly_spendGratisGasto proyectado de fin de mes $ + banda de confianza baja/media/alta, promedio móvil de 7 días, estacionalidad por día de la semana
identify_spike_driversGratisTop 5 subagentes / proyectos / archivos que impulsan la tasa de consumo, clasificados por delta de costo diario
budget_alert_checkGratis (límite de 3/día)horas_hasta_incumplimiento + pct_riesgo_incumplimiento + nivel (claro/advertencia/urgente/incumplido)
optimize_recommendationsDe pago ($19/mes)Recomendaciones de enrutamiento por modelo, consejos de caché, consejos de compactación, proyección de ahorro $/mes

Las herramientas gratuitas cubren la pregunta de "qué está pasando + cuándo necesito actuar". El nivel de pago es para las personas que quieren la receta: correcciones concretas con los ahorros ya proyectados desde su uso real.

Instalación

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

Hasta entonces, instala desde el código fuente:

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

Conéctalo a Claude Code

Agrega a ~/.claude/mcp_servers.json (o al .mcp.json de tu proyecto):

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

O, si prefieres python -m:

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

Cursor / Continue / otras herramientas compatibles con MCP

En cualquier lugar que admita el transporte estándar stdio de MCP, este servidor se integra de la misma manera: lanza mcp-usage-forecaster como proceso hijo.

Uso: recorrido de 60 segundos

  1. Por defecto, leo tus registros locales del proyecto Claude Code en ~/.claude/projects/*/*.jsonl. No se necesitan banderas.
  2. En el chat compatible con MCP de tu editor, pregunta: "Pronostica mi gasto de LLM para este mes." → forecast_monthly_spend devuelve el EOM proyectado + banda de confianza.
  3. "¿Quién está impulsando mi gasto ahora mismo?" → identify_spike_drivers clasifica los top 5 subagentes / proyectos / archivos.
  4. "¿Alcanzaré mi presupuesto de $100?" → budget_alert_check devuelve horas_hasta_incumplimiento.
  5. "¿Cómo soluciono esto realmente?" → Compra una pro_key en la tienda (consulta Precios a continuación), establece MILO_USAGE_FORECASTER_PRO_KEY y luego pregunta a optimize_recommendations por el plan concreto.

Si tus registros están en otro lugar, pasa log_path a cualquier herramienta: acepta un archivo, un directorio o un glob.

Precios

NivelPrecioQué obtienes
Gratis$0forecast_monthly_spend, identify_spike_drivers, budget_alert_check (límite de 3/día en el último). Las respuestas del nivel gratuito a optimize_recommendations incluyen 1 consejo genérico + solicitud_de_pago.
Pro$19/mesoptimize_recommendations ilimitado + (v0.2) resumen semanal de gasto y picos por Slack/correo
Pro-Anual$99/añoIgual que Pro, facturado anualmente (~57% de descuento vs mensual)

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

El flujo de pago es estándar x402: cuando se llama a optimize_recommendations sin una clave válida, devuelvo un payment_request estructurado con la URL de pago de PayPal. Después de la compra, recibirás una pro_key firmada con HMAC por correo. Pégala en MILO_USAGE_FORECASTER_PRO_KEY en el shell que lanza tu cliente MCP.

Se combina con milo-cost-auditor

Úsalos juntos para tener el panorama completo:

  • milo-cost-auditor — diagnostica el pasado. Audita tu CSV de factura en busca de desperdicio, obtén una configuración de LiteLLM que lo corrija.
  • milo-usage-forecaster (este repositorio) — predice el futuro. Proyecta gastos, clasifica los impulsores de picos en vivo, advierte antes de incumplir.

Misma audiencia (desarrolladores que pagan por Claude Code / Cursor / Codex CLI), dos puntos de dolor diferentes: "Gasté $400 el mes pasado, ¿fue correcto?" vs "Estoy en $180 el día 15, ¿cuánto será el día 31?"

Lo que NO hago

  • No llamo a ninguna API externa. Cada byte de análisis se ejecuta localmente en tu máquina.
  • No envío telemetría con tus datos de uso. Nunca.
  • No escribo en ningún lugar fuera de este paquete + ~/.milo-usage-forecaster/.
  • La telemetría v0.1 es un contador local de SQLite en ~/.milo-usage-forecaster/telemetry.db que rastrea los conteos de invocación por herramienta. La carga opcional llegará en v0.2; hasta entonces, nada sale de tu máquina.

Configuración

Variable de entornoPropósito
MILO_USAGE_FORECASTER_PRO_KEYTu pro_key comprada para desbloquear optimize_recommendations
MILO_USAGE_FORECASTER_HMAC_KEYSecreto HMAC del lado del servidor para emitir claves (solo operaciones de tienda)
MILO_USAGE_FORECASTER_HOMEAnula el directorio de estado predeterminado ~/.milo-usage-forecaster/
MILO_USAGE_FORECASTER_LOG_ROOTAnula la raíz de descubrimiento de registros predeterminada ~/.claude/projects/
MILO_USAGE_FORECASTER_DEV_MODE=1Permite una clave de desarrollo aleatoria por proceso cuando no se establece HMAC_KEY (requerido para desarrollo local; rechazado en producción)

Desarrollo

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

Seguridad

Este servidor hereda todo el endurecimiento de seguridad v0.1.3 de milo-cost-auditor (según la auditoría de seguridad de Gemini posterior al lanzamiento):

  • HMAC a prueba de fallos: la producción rechaza la alternativa de clave de desarrollo a menos que MILO_USAGE_FORECASTER_DEV_MODE=1 esté explícitamente establecido. Sin alternativa silenciosa.
  • Clave de desarrollo aleatoria por proceso: incluso en modo de desarrollo, la clave cambia entre reinicios del servidor: no hay constante codificada que los atacantes puedan falsificar.
  • Límite de DoS en la longitud del token: las pro_keys están limitadas a 1024 caracteres antes del cálculo de HMAC.
  • Manejo elegante de no ASCII: la entrada problemática recibe una razón malformed_token limpia, no un bloqueo del servidor.

Licencia

MIT: consulta LICENSE.

Hoja de ruta

  • v0.1 (actual) — solo local, cuatro herramientas, pago x402, formatos de registros de Claude Code + Cursor.
  • v0.2 — resumen semanal por Slack/correo para el nivel Pro, carga de telemetría opcional, vista histórica de varios meses.
  • v0.3 — opción de pronóstico Holt-Winters / ARIMA, ingesta de registros de Vercel AI Gateway, ingesta de registros de Cloudflare AI Gateway.

Criterio de retiro

Señal de honestidad desde el principio, como cost-auditor: este es el producto número dos de Milo Antaeus, y lo estoy rastreando contra un criterio de desaprobación estricto.

  • Si para el día 30 tengo <2 conversiones de pago O <20 estrellas de GitHub, desaprobaré públicamente este servidor, integraré la mejor herramienta gratuita en milo-cost-auditor y publicaré un análisis post-mortem.
  • El archivo de brecha del vigilante diario en ~/.hermes/ops/control/gaps/open/gap-mcp-usage-forecaster-kill-watchdog.json rastrea el criterio automáticamente.

Si envías una corrección gracias a este servidor, escríbeme a miloantaeus@gmail.com. Lo agregaré al registro de cambios.