Token Meter

Panel local y servidor MCP para el seguimiento del uso de tokens en Claude Code y Codex.

GitHub
1
Prueba este MCPPatrocinado

Documentación

Token Meter

Token Meter

Controla el uso de tokens y costos de Claude Code, Codex y Cursor localmente — sin cuenta, sin nube.

Un único panel local para el uso de tokens de Claude Code y Codex. Núcleo gratuito, compatible con MCP, con licencia MIT.

npm: @whdrnr2583/token-meter · GitHub: whdrnr2583-cmd/token-meter · Sitio: token-meter.dev

Token Meter analiza los archivos JSONL que Claude Code y Codex ya escriben en disco y los convierte en un panel real: costo por proyecto, por modelo, por herramienta MCP, por hora. Tus datos nunca salen de tu máquina.

Ejecuta tu primera auditoría

npx -y @whdrnr2583/token-meter audit

Escanea tu historial ingerido de Claude Code + Codex en busca de sesiones costosas, respuestas de herramientas sobredimensionadas, herramientas lentas, llamadas repetidas y desperdicio de caché, clasificados por costo y confianza. Se ejecuta íntegramente contra tu base de datos SQLite local — el mismo procesamiento local-primero, sin nube que el resto de Token Meter. Añade --json para salida legible por máquina; consulta docs/audit.md para la lista completa de banderas y el esquema JSON.

Cuándo usarlo

Usa Token Meter si:

  • quieres saber cuántos tokens y dólares están costando tus sesiones de Claude Code o Codex — desglosado por proyecto, modelo y herramienta MCP
  • estás en un plan de tarifa plana (Claude Max, etc.) y quieres ver cuál sería el costo equivalente de la API
  • quieres averiguar qué servidor o herramienta MCP consume más tokens, o qué hora del día es la más cara
  • quieres reanudar una sesión reciente y necesitas tener a mano el comando claude --resume / codex resume
  • quieres todo lo anterior sin conexión, sin cuenta y sin subir nada

No es adecuado si necesitas cifras de nivel de facturación validadas contra tu factura de Anthropic u OpenAI — Token Meter calcula estimaciones únicamente a partir de archivos JSONL locales.

Herramientas MCP

Cuando Token Meter está conectado como servidor MCP (install-mcp all), cuatro herramientas quedan disponibles para tu asistente de IA:

HerramientaQué devuelve
usage_summaryTabla diaria de recuentos de tokens, costo equivalente en USD y recuentos de llamadas — desglosado por día y modelo
recent_sessionsSesiones recientes con comandos claude --resume / codex resume listos para pegar
session_toolsDesglose por herramienta dentro de una sesión: número de llamadas, tokens totales, latencia media, tamaño de respuesta
refresh_dataReescanea tus registros JSONL locales en busca de nueva actividad y devuelve un resumen actualizado

Las cuatro son de solo lectura. Ningún dato sale de tu máquina.

Ejemplos de prompts

Copia y pega cualquiera de estos en Claude Code o Cursor después de instalar el servidor MCP:

Show me my token usage and cost for the last 7 days.

List my recent sessions so I can pick one to resume.

Show the tool breakdown for my most recent session — which tool used the most tokens?

Refresh token-meter data, then tell me which model cost the most this week.

Which hour of the day am I spending the most tokens on?

Inicio rápido

npx @whdrnr2583/token-meter ingest        # scan ~/.claude/projects + ~/.codex/sessions
npx @whdrnr2583/token-meter stats 30      # CLI summary for last 30 days
npx @whdrnr2583/token-meter serve         # http://localhost:8765 dashboard
npx @whdrnr2583/token-meter mcp           # run as an MCP server for Claude Code / Cursor

El paquete se publica bajo un ámbito de npm (@whdrnr2583/) porque el nombre simple token-meter choca con un nombre similar existente en npm. El binario de la CLI sigue llamándose token-meter tras la instalación.

Conecta Token Meter a tu herramienta de IA (MCP)

Un solo comando registra Token Meter con todos los clientes compatibles de tu máquina:

npx -y @whdrnr2583/token-meter install-mcp all

Gestiona Claude Code, Cursor y Claude Desktop — idempotente, hace copia de seguridad de la configuración existente y conserva otros servidores MCP. Variantes de un solo cliente: install-mcp claude-code | cursor | claude-desktop. Añade --dry-run para previsualizar.

O deja que tu LLM lo haga. Abre Claude Code / Cursor / Claude Desktop y pide: "Lee https://raw.githubusercontent.com/whdrnr2583-cmd/token-meter/main/docs/mcp-server.md y configura token-meter como mi servidor MCP."

Comandos manuales de una línea (si prefieres no ejecutar nuestro instalador):

ClienteComando / configuración
Claude Codeclaude mcp add token-meter -- npx -y @whdrnr2583/token-meter mcp y luego claude mcp list para verificar
CursorEdita ~/.cursor/mcp.json (Windows: %USERPROFILE%\.cursor\mcp.json) — consulta docs/mcp-server.md
Claude DesktopEdita claude_desktop_config.json — consulta docs/mcp-server.md
ChatGPTSolo stdio por ahora; receta de envoltorio HTTP en docs/mcp-server.md
Otros (Continue, Zed, personalizado)npx -y @whdrnr2583/token-meter mcp sobre stdio

Luego pide: "Usa token-meter para mostrar mis sesiones recientes" o "Usa token-meter usage_summary para esta semana".

Atajo de Claude Code: ejecuta npx -y @whdrnr2583/token-meter install-command claude-code una vez para registrar el comando de barra /token-meter. Después de reabrir tu sesión, escribe /token-meter para obtener un resumen de una sola vez sin lenguaje natural.

Configuración completa + verificación + solución de problemas: docs/mcp-server.md.

Almacenamiento: ~/.tokenpulse/usage.db (SQLite). Elimina la carpeta para empezar de nuevo. El nombre de la carpeta pasará a ser ~/.tokenmeter/ en una futura versión con migración automática; hasta entonces, el directorio v0.1 conserva su nombre original.

Lo que verás

  • Costo equivalente en USD por día, modelo y proyecto. Útil si estás en un plan Max y quieres saber cuánto habría costado la API.
  • Desglose de MCP y herramientas: qué servidor MCP consume tokens, cuánta latencia media tiene cada herramienta, tamaños de respuesta por llamada.
  • Distribución horaria de los tokens de salida.
  • Claude Code + Codex lado a lado, en una sola vista.

Nota sobre las cifras en dólares

Los costos son estimaciones calculadas localmente a partir de los recuentos de tokens que Claude Code y Codex ya escriben en sus archivos JSONL, multiplicados por la tarifa publicada por millón de tokens del modelo. No están validados contra tu factura real de Anthropic / OpenAI y pueden divergir por varias razones:

  • Los proveedores cambian los precios; la tabla en src/pricing.ts es una instantánea
  • Los planes de suscripción (Pro / Max) cobran una tarifa plana — el $ en pantalla es lo que habría costado la API, no lo que pagas
  • Algunas categorías de tokens (uso de herramientas del lado del servidor, variantes de escritura de caché) se aproximan

Trata las cifras como señal relativa para detectar desperdicio, no como contabilidad de nivel de facturación. Token Meter incluye una prueba de regresión que garantiza que el cálculo es reproducible y un script de auditoría que verifica invariantes; ninguno verifica las tarifas contra las facturas de los proveedores.

Por qué local-primero

  • Tu JSONL contiene código fuente, prompts y resultados de herramientas. Token Meter nunca sube nada de eso. Solo heurísticas, regex y agregación SQL.
  • Sin SDK que integrar, sin proxy que configurar para el nivel gratuito.
  • La CLI y el núcleo del panel tienen licencia MIT.

Precios

NivelPrecioQué incluye
Gratis$0Análisis de Claude Code + Codex, desglose MCP/herramientas, desglose por hora/modelo/proyecto, historial de 7 días, 1 alerta de escritorio
Pro$5/mesTodo lo de Gratis, reformulado como revisión de gasto mensual: historial de 30 días (este mes vs. el anterior), desglose por sesión/mensaje hasta la ejecución que superó el presupuesto, dólares ahorrados por eficiencia de caché, señales de desperdicio (respuestas de herramientas sobredimensionadas + caché que no compensó), además de alertas inteligentes ilimitadas (escritorio + webhook)
Pro+próximamenteProxy LLM local (Ollama / LM Studio / llama.cpp / vLLM), seguimiento de GPU/VRAM, acciones automáticas

Pro es la diferencia entre echar un vistazo a la cifra de la semana pasada y revisar dónde se filtró el gasto del mes. Pro está disponible — Suscríbete en token-meter.dev.

Pro+ se lanzará cuando los registros de Pro + la demanda de la comunidad confirmen el segmento.

Hoja de ruta

  • M1 ✅ Análisis de Claude Code, desglose MCP/herramientas, estadísticas horarias
  • M2 ✅ Integración de Codex
  • M3 Nivel Pro ($5), facturación Polar.sh, activación de licencia
  • M4+ Pro+ (proxy LLM local, seguimiento de GPU), condicionado a la demanda

Privacidad y seguridad

  • Los tokens se cuentan a partir de los archivos JSONL que Claude Code y Codex ya escriben. Token Meter no toca las API de red de ninguno de los dos proveedores.
  • No se almacenan cuerpos de prompts ni respuestas por defecto — solo metadatos (marcas de tiempo, recuentos de tokens, nombres de herramientas, longitudes de respuesta).
  • La base de datos se encuentra en ~/.tokenpulse/; elimínala para borrarlo todo. (Se renombrará a ~/.tokenmeter/ en una futura versión con migración automática.)

Registro de cambios

Consulta CHANGELOG.md para las notas de versión y los cambios importantes.

Licencia

MIT para la CLI, el panel y los analizadores. Las funciones del nivel Pro se distribuyen en un paquete separado bajo una licencia de código cerrado.