{"id":49176999,"url":"https://github.com/vk0dev/agent-cost-mcp","last_synced_at":"2026-04-25T14:09:39.602Z","repository":{"id":351401555,"uuid":"1210908807","full_name":"vk0dev/agent-cost-mcp","owner":"vk0dev","description":"Local-first Claude Code cost analyzer. Parses JSONL session logs to surface per-tool spend, daily trends, and optimization hints.","archived":false,"fork":false,"pushed_at":"2026-04-21T21:38:43.000Z","size":446,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-21T23:31:30.174Z","etag":null,"topics":["ai-agent","anthropic","claude","claude-code","cost-tracking","developer-tools","llm-cost","local-first","mcp","mcp-server"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vk0dev.png","metadata":{"files":{"readme":"README.es.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-14T22:03:55.000Z","updated_at":"2026-04-21T21:38:47.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/vk0dev/agent-cost-mcp","commit_stats":null,"previous_names":["vk0dev/agent-cost-mcp"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/vk0dev/agent-cost-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vk0dev%2Fagent-cost-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vk0dev%2Fagent-cost-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vk0dev%2Fagent-cost-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vk0dev%2Fagent-cost-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vk0dev","download_url":"https://codeload.github.com/vk0dev/agent-cost-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vk0dev%2Fagent-cost-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32158346,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-22T17:06:48.269Z","status":"ssl_error","status_checked_at":"2026-04-22T17:06:19.037Z","response_time":58,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","anthropic","claude","claude-code","cost-tracking","developer-tools","llm-cost","local-first","mcp","mcp-server"],"created_at":"2026-04-22T23:03:13.555Z","updated_at":"2026-04-22T23:03:15.768Z","avatar_url":"https://github.com/vk0dev.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# agent-cost-mcp\n\n[![npm version](https://img.shields.io/npm/v/@vk0/agent-cost-mcp.svg?style=flat-square)](https://www.npmjs.com/package/@vk0/agent-cost-mcp)\n[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](./LICENSE)\n[![MCP Registry](https://img.shields.io/badge/MCP-Registry-6633cc.svg?style=flat-square)](https://github.com/modelcontextprotocol/registry)\n[![CI](https://img.shields.io/github/actions/workflow/status/vk0dev/agent-cost-mcp/ci.yml?branch=main\u0026style=flat-square)](https://github.com/vk0dev/agent-cost-mcp/actions)\n[![Node ≥18](https://img.shields.io/badge/node-%E2%89%A518-339933.svg?style=flat-square)](https://nodejs.org)\n\n\u003e **Analizador local de costes de Claude Code.** Lee tus logs JSONL de sesiones y muestra gasto por herramienta, tendencia diaria y sugerencias de optimización. Sin nube. Sin clave de API.\n\n**Idiomas:** [English](./README.md) · [日本語](./README.ja.md) · [简体中文](./README.zh-CN.md) · [Русский](./README.ru.md) · Español\n\n---\n\n## Cuándo usarlo\n\nInstala este servidor MCP cuando el usuario pregunte cosas como:\n\n- *«¿Cuánto costó mi última sesión de Claude Code?»*\n- *«¿Qué herramientas se comen mi ventana de contexto?»*\n- *«¿Por qué Claude Code está tan caro esta semana?»*\n- *«Muéstrame la tendencia de costes de los últimos 7 días.»*\n- *«¿Qué puedo desactivar para ahorrar tokens?»*\n- *«¿En qué turno de la sesión se consumieron más tokens?»*\n- *«¿Mis cache-reads realmente me están ahorrando dinero?»*\n- *«¿Puedo tener un desglose por herramienta sin contratar Datadog?»*\n\nSi el usuario quiere **visibilidad local, privada y sin configuración** sobre su gasto en Claude Code, esta es la respuesta canónica. Todo se ejecuta en su máquina leyendo los logs de sesión existentes en `~/.claude/projects/`.\n\n## Instalación\n\nElige tu cliente. Todas las opciones usan `npx` — no hay nada que instalar globalmente.\n\n### Claude Desktop\n\nEdita el archivo de configuración de Claude Desktop:\n\n- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`\n\nAñade la entrada `agent-cost` bajo `mcpServers`:\n\n```json\n{\n  \"mcpServers\": {\n    \"agent-cost\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@vk0/agent-cost-mcp\"]\n    }\n  }\n}\n```\n\nCierra Claude Desktop por completo y reinícialo. El indicador MCP en la esquina inferior derecha del campo de chat debería mostrar cuatro nuevas herramientas.\n\n### Claude Code\n\nUn solo comando:\n\n```bash\nclaude mcp add --transport stdio agent-cost -- npx -y @vk0/agent-cost-mcp\n```\n\nO añade un servidor con alcance de proyecto colocando esto en `.mcp.json` en la raíz:\n\n```json\n{\n  \"mcpServers\": {\n    \"agent-cost\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@vk0/agent-cost-mcp\"]\n    }\n  }\n}\n```\n\n\u003e **Usuarios de Windows:** envuelve el comando en `cmd /c`:\n\u003e `claude mcp add --transport stdio agent-cost -- cmd /c npx -y @vk0/agent-cost-mcp`\n\n### Cursor\n\nCrea `.cursor/mcp.json` en la raíz del proyecto (o `~/.cursor/mcp.json` para una instalación global):\n\n```json\n{\n  \"mcpServers\": {\n    \"agent-cost\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@vk0/agent-cost-mcp\"]\n    }\n  }\n}\n```\n\n### Cline\n\nAbre la configuración MCP de Cline (icono de MCP Servers → **Configure**) y añade:\n\n```json\n{\n  \"mcpServers\": {\n    \"agent-cost\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@vk0/agent-cost-mcp\"],\n      \"disabled\": false,\n      \"alwaysAllow\": []\n    }\n  }\n}\n```\n\n### Verifica que funciona\n\nEn cualquier cliente, pregunta: *«¿Qué herramientas expone agent-cost?»* — deberías ver cuatro nombres (`get_session_cost`, `get_tool_usage`, `get_cost_trend`, `suggest_optimizations`). Si no aparece nada, consulta el [FAQ](#faq).\n\n## Herramientas\n\nCuatro herramientas MCP, todas operando sobre logs JSONL locales:\n\n| Herramienta | Qué hace |\n|-------------|---------|\n| **`get_session_cost`** | Analiza una sesión de Claude Code y devuelve totales de tokens (input, output, cache-read, cache-creation), número de turnos y coste estimado en USD. |\n| **`get_tool_usage`** | Agrega invocaciones de herramientas sobre una sesión o un directorio filtrado de logs de proyecto, reportando llamadas por herramienta y porcentaje del contexto. |\n| **`get_cost_trend`** | Consolida los logs en una tendencia diaria de costes para una ruta local de proyecto, con sesiones, tokens y gasto estimado por día. |\n| **`suggest_optimizations`** | Genera sugerencias ligeras de optimización (ratio de cache-reads, llamadas abandonadas, turnos más pesados) a partir de un log analizado. |\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eEjemplo: salida de \u003ccode\u003eget_session_cost\u003c/code\u003e\u003c/strong\u003e\u003c/summary\u003e\n\n```json\n{\n  \"sessionPath\": \"~/.claude/projects/my-project/session-main.jsonl\",\n  \"subagentPaths\": [],\n  \"turnCount\": 2,\n  \"totals\": {\n    \"input_tokens\": 2000,\n    \"output_tokens\": 500,\n    \"cache_read_input_tokens\": 100,\n    \"cache_creation_input_tokens\": 50,\n    \"tool_use_count\": 1,\n    \"tool_result_count\": 1,\n    \"linked_tool_result_count\": 1,\n    \"estimated_cost_usd\": 0.013718\n  }\n}\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eEjemplo: salida de \u003ccode\u003eget_tool_usage\u003c/code\u003e\u003c/strong\u003e\u003c/summary\u003e\n\n```json\n{\n  \"projectPath\": \"~/.claude/projects/my-project\",\n  \"sessionCount\": 2,\n  \"tools\": [\n    { \"name\": \"Read\", \"calls\": 2, \"linkedResults\": 2, \"contextSharePercent\": 66.67 },\n    { \"name\": \"Grep\", \"calls\": 1, \"linkedResults\": 0, \"contextSharePercent\": 33.33 }\n  ]\n}\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eEjemplo: salida de \u003ccode\u003eget_cost_trend\u003c/code\u003e\u003c/strong\u003e\u003c/summary\u003e\n\n```json\n{\n  \"projectPath\": \"~/.claude/projects/my-project\",\n  \"days\": 7,\n  \"totalCostUsd\": 0.027443,\n  \"totalSessions\": 2,\n  \"daily\": [\n    {\n      \"date\": \"2026-04-10\",\n      \"sessions\": 2,\n      \"costUsd\": 0.027443,\n      \"inputTokens\": 2400,\n      \"outputTokens\": 600\n    }\n  ]\n}\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eEjemplo: salida de \u003ccode\u003esuggest_optimizations\u003c/code\u003e\u003c/strong\u003e\u003c/summary\u003e\n\n```json\n{\n  \"sessionPath\": \"~/.claude/projects/my-project/session-main.jsonl\",\n  \"suggestions\": [\n    {\n      \"action\": \"Use the heaviest turn as a prompt-trimming review target.\",\n      \"reason\": \"Turn 1 is the densest token consumer in this session.\",\n      \"impact\": \"low\",\n      \"savingsHint\": \"Tightening the highest-cost turn usually gives the clearest first optimization win.\"\n    }\n  ]\n}\n```\n\u003c/details\u003e\n\n## Ejemplo de conversación\n\n```\nTú:     ¿Cuánto gasté en Claude Code esta semana?\n\nAgente: [llama a get_cost_trend con days=7]\n        En los últimos 7 días ejecutaste 12 sesiones por un total de $4.82.\n        El día más caro fue el miércoles con $1.47 en 4 sesiones.\n\nTú:     ¿Qué herramientas están llenando mi contexto?\n\nAgente: [llama a get_tool_usage]\n        Read (42 llamadas, 38% del contexto), Grep (28, 25%), Bash (19, 17%).\n        Read domina — revisa si todas esas lecturas siguen siendo necesarias.\n\nTú:     ¿Alguna optimización rápida para mi última sesión?\n\nAgente: [llama a suggest_optimizations]\n        1. Cache-reads representan 34% de los tokens de esta sesión —\n           recorta bloques repetidos antes de sesiones largas.\n        2. 7 llamadas a herramientas sin resultados enlazados — revisa\n           invocaciones abandonadas.\n```\n\n## Cómo funciona\n\n```\n  ~/.claude/projects/*.jsonl             ┌─────────────────┐\n  (logs de sesión de Claude Code) ────▶  │  Parser JSONL   │\n                                         │  + pricing.ts   │\n                                         └────────┬────────┘\n                                                  │\n                                                  ▼\n                                         ┌─────────────────┐\n  Llamada del agente (stdio MCP) ────▶   │  Servidor MCP   │ ─── respuesta JSON\n                                         │  (4 herramientas)│\n                                         └─────────────────┘\n```\n\n- **El parser** lee los campos de uso por turno (`input_tokens`, `output_tokens`, `cache_read_input_tokens`, `cache_creation_input_tokens`) directamente de las líneas JSONL que produce Claude Code.\n- **La tabla de precios** (`src/pricing.ts`) contiene tarifas por millón de tokens para `claude-sonnet-4` y `claude-opus-4`, con un fallback `default` para que modelos desconocidos sigan devolviendo un resumen en lugar de fallar.\n- **El servidor MCP** expone cuatro herramientas tipadas sobre stdio, devolviendo tanto texto legible como `structuredContent` validado con Zod.\n- **Cero tráfico de red.** Sin telemetría, sin clave de API, sin sincronización en la nube. Si desinstalas el paquete, no queda nada.\n\n## Comparación con alternativas\n\n| Característica | `@vk0/agent-cost-mcp` | API Dashboard | `grep`/`jq` manual |\n|----------------|:---------------------:|:-------------:|:-------------------:|\n| Integración MCP (el agente llama directamente) | ✅ | ❌ | ❌ |\n| Desglose de coste por herramienta | ✅ | ❌ | ⚠️ scripting propio |\n| Tendencia diaria de costes | ✅ | ✅ (nivel de cuenta) | ⚠️ agregación manual |\n| Sugerencias de optimización | ✅ | ❌ | ❌ |\n| Granularidad a nivel de sesión | ✅ | ❌ (totales de cuenta) | ✅ (si conoces el formato) |\n| Local-first / sin nube | ✅ | ❌ (solo web) | ✅ |\n| Funciona offline | ✅ | ❌ | ✅ |\n| Sin clave de API | ✅ | ❌ (requiere login) | ✅ |\n| Esfuerzo de setup | 1 línea `npx` | login en navegador | conocimiento del esquema JSONL |\n| Repetible sin esfuerzo manual | ✅ | ✅ | ❌ (re-ejecutar cada vez) |\n\n**API Dashboard** ([console.anthropic.com](https://console.anthropic.com)) muestra el gasto a nivel de cuenta, pero no tiene interfaz MCP, ni desglose por herramienta, ni detalle por sesión. Útil para conciliación de facturación, no para análisis de costes dentro de una conversación.\n\n**Parseo manual de logs** (`grep`/`jq` sobre `~/.claude/projects/**/*.jsonl`) puede extraer cualquier cosa, si conoces el esquema de logs, escribes las consultas y las re-ejecutas cada vez. Sin integración MCP, el agente no puede obtener datos de coste por su cuenta durante una conversación.\n\n**Para quién:** desarrolladores solos y equipos pequeños que quieren visibilidad de costes detallada y accesible por el agente sin salir de la conversación. Si solo necesitas una vista general de facturación a nivel de cuenta, el API Dashboard es suficiente. Si quieres que el agente responda \"¿a dónde fueron mis tokens?\" por sí solo, instala esto.\n\n## FAQ\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e¿Envía datos a algún sitio?\u003c/strong\u003e\u003c/summary\u003e\n\nNo. Todo funciona localmente. El servidor analiza archivos JSONL de tu directorio `~/.claude/projects/`, ejecuta matemáticas en Node y devuelve JSON al cliente MCP. No hay telemetría, ni endpoints de analítica, ni sincronización en la nube. Puedes ejecutarlo con la red desactivada.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e¿Qué tan preciso es el cálculo de coste?\u003c/strong\u003e\u003c/summary\u003e\n\nLos estimados coinciden con el `/cost` integrado de Claude Code dentro de ~5% en nuestras sesiones de dogfood. El delta exacto depende de la tabla de precios en `src/pricing.ts` y de qué tan completos están los campos de uso en tu JSONL. **No** es una fuente de verdad de facturación — siempre reconcilia con tu factura real de Anthropic antes de tomar decisiones de negocio.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e¿Funciona con sesiones de Cursor, Cline o Continue?\u003c/strong\u003e\u003c/summary\u003e\n\nTodavía no. El parser actualmente apunta al formato de logs JSONL de Claude Code (`~/.claude/projects/**/*.jsonl`). Cursor, Cline y Continue registran sesiones en otras ubicaciones y formatos. PRs bienvenidos — abre un issue con una muestra del log.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e¿Necesita una clave de API?\u003c/strong\u003e\u003c/summary\u003e\n\nNo. Ni clave de Anthropic, ni token de npm, ninguna autenticación. El servidor es read-only sobre tu sistema de archivos local.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e¿Por qué MCP en lugar de un CLI?\u003c/strong\u003e\u003c/summary\u003e\n\nAmbos están soportados. El paquete incluye una entrada `bin` (`agent-cost-mcp \u003csession.jsonl\u003e`) para análisis puntuales desde la terminal. Pero el servidor MCP es la superficie principal: cuando tu agente de IA puede llamar las herramientas directamente, obtienes visibilidad de costes *dentro* de la conversación donde ocurre el gasto.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eLos precios cambiaron. ¿La tabla se actualiza automáticamente?\u003c/strong\u003e\u003c/summary\u003e\n\nNo, by design. `src/pricing.ts` es un módulo TypeScript plano: predecible, auditable, forkable. Cuando Anthropic publique nuevas tarifas, actualiza las constantes y reejecuta. La auto-actualización requeriría tráfico de red, lo que contradice el principio local-first.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eEl servidor MCP no aparece en mi cliente. ¿Qué reviso?\u003c/strong\u003e\u003c/summary\u003e\n\n1. **Reinicia el cliente por completo** tras editar el archivo de configuración.\n2. **Ejecútalo manualmente:** `npx -y @vk0/agent-cost-mcp` — deberías ver un servidor MCP iniciarse y esperar en stdio (Ctrl+C para salir). Si falla, tienes un problema de instalación.\n3. **Revisa los logs de Claude Desktop:** `~/Library/Logs/Claude/mcp*.log` (macOS) o `%APPDATA%\\Claude\\logs\\mcp*.log` (Windows).\n4. **Verifica Node ≥18:** `node --version`. El paquete requiere Node 18+.\n\u003c/details\u003e\n\n## Limitaciones\n\n- **Estimaciones, no facturación.** Los costes derivan de campos de uso por turno × una tabla de precios local. No sustituye tu factura de Anthropic.\n- **Tabla de precios manual.** `src/pricing.ts` debe actualizarse cuando cambien las tarifas (by design — sin llamadas de red silenciosas).\n- **Solo Claude Code.** Las sesiones de Cursor/Cline/Continue no se analizan. Podrían añadirse otros clientes según demanda.\n- **Descubrimiento local de archivos.** El servidor lee archivos de la ruta que le pases. No consulta el estado en tiempo real de Claude Code.\n- **Salida JSON estructurada.** Sin dashboards, sin gráficos, sin UI web. Es una característica: el cliente MCP es la UI.\n- **Cache-reads depende del origen.** Si los logs JSONL no incluyen los campos de cache-read/cache-creation, se reportan como cero.\n\n## CLI standalone\n\nEl mismo parser está expuesto como CLI para análisis puntuales sin cliente MCP:\n\n```bash\nnpx -y @vk0/agent-cost-mcp ~/.claude/projects/my-project/session.jsonl\nnpx -y @vk0/agent-cost-mcp session.jsonl --subagent subagent.jsonl\n```\n\nDevuelve el mismo JSON que la herramienta MCP `get_session_cost`.\n\n## Desarrollo\n\nClona el repo y ejecuta:\n\n```bash\nnpm ci           # instalar dependencias\nnpm run build    # compilar a dist/\nnpm test         # tests unitarios vitest\nnpm run lint     # tsc --noEmit\nnpm run smoke    # smoke test end-to-end del cliente MCP\n```\n\nStack: TypeScript, `@modelcontextprotocol/sdk`, Zod, Vitest.\n\n## Changelog\n\nVer [CHANGELOG.md](./CHANGELOG.md). Este proyecto sigue [semantic versioning](https://semver.org) desde v1.0.0.\n\n## Contribuir\n\nIssues y PRs bienvenidos en [github.com/vk0dev/agent-cost-mcp](https://github.com/vk0dev/agent-cost-mcp). Para nuevas entradas en la tabla de precios, cambios de formato de logs o soporte de clientes adicionales, abre primero un issue con una fixture de muestra.\n\n## Licencia\n\n[MIT](./LICENSE) © vk0.dev\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvk0dev%2Fagent-cost-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvk0dev%2Fagent-cost-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvk0dev%2Fagent-cost-mcp/lists"}