{
  "markdown": "# MCP Cost Tracker & Router\n\nnpm `mcp-cost-tracker-router` package\n\nLocal-first cost awareness for MCP agent workflows. Token counts are calculated offline using js-tiktoken — no proxy, no API round-trip, no spend data leaving your machine. When costs climb, routing suggestions point you to cheaper models before the invoice arrives.\n\n[Tool reference](#tools) | [Configuration](#configuration) | [Contributing](#contributing) | [Troubleshooting](#troubleshooting)\n\n## Key features\n\n- **Per-tool cost breakdown**: See exactly which tool calls are consuming the most tokens and budget.\n- **Budget alerts**: Set a session spend threshold and get warned at 80% and 100% before you exceed it.\n- **Offline token counting**: Uses js-tiktoken for accurate counts — no API calls required.\n- **Model routing suggestions**: Recommends cheaper models for the current task type (advisory, never enforced without opt-in).\n- **Multi-provider pricing**: Tracks costs across Claude, OpenAI, and Gemini models from a single configurable pricing table.\n- **Spend history**: Query daily, weekly, and monthly totals by model or tool.\n- **Project cost allocation**: Tag sessions to named projects and generate chargeback reports.\n- **HTML spend reports**: Export a single-file, self-contained HTML report with charts and budget status.\n- **Audit log**: Append-only log of every budget enforcement decision.\n\n## Why this over proxy-based cost trackers?\n\nMost cost-tracking tools work by routing all your API traffic through their server and measuring tokens server-side. That means your prompts and responses transit a third-party service, and you're dependent on their uptime.\n\n|                   | mcp-cost-tracker-router                     | Proxy-based trackers (Helicone, LLMonitor, etc.) |\n| ----------------- | ------------------------------------------- | ------------------------------------------------ |\n| Token counting    | Offline via js-tiktoken — no network call   | Counted server-side after traffic is proxied     |\n| Data residency    | Local SQLite only                           | Prompts + responses pass through vendor servers  |\n| Model routing     | Built-in `suggest_model_routing` tool       | Rarely included; usually a separate paid tier    |\n| Multi-provider    | Claude, OpenAI, Gemini in one pricing table | Often single-provider or requires separate setup |\n| Uptime dependency | None — fully offline                        | Breaks if proxy is down                          |\n\nIf your prompts contain sensitive information or you can't route traffic through a third party, this is the right tool. If you need a managed dashboard with team sharing, a proxy-based service may suit you better.\n\n## Disclaimers\n\n`mcp-cost-tracker-router` stores tool call metadata (token counts, model names, timestamps) locally in SQLite. It does not store prompt or response content. Cost calculations are estimates based on a local pricing table and may not exactly match your provider's invoice.\n\n## Requirements\n\n- Node.js v20.19 or newer.\n- npm.\n\n## Getting started\n\nAdd the following config to your MCP client:\n\n```json\n{\n  \"mcpServers\": {\n    \"cost-tracker\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-cost-tracker-router@latest\"]\n    }\n  }\n}\n```\n\nTo set a session budget alert:\n\n```json\n{\n  \"mcpServers\": {\n    \"cost-tracker\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-cost-tracker-router@latest\", \"--budget-alert=5.00\"]\n    }\n  }\n}\n```\n\n### MCP Client configuration\n\nAmp · Claude Code · Cline · Cursor · VS Code · Windsurf · Zed\n\n## Your first prompt\n\nEnter the following in your MCP client to verify everything is working:\n\n```\nHow much has this session cost so far?\n```\n\nYour client should return a token and USD cost summary for the current session.\n\n## Tools\n\n### Session (4 tools)\n\n- `get_session_cost` — Returns token totals and USD cost estimates for the current session. Read-only.\n- `get_tool_costs` — Returns per-tool cost breakdown for the session, sorted by cost descending. Read-only.\n- `reset_session` — Start a new cost-tracking session. Previous session data is retained in history.\n- `record_usage` — Record token usage for a tool call. Takes `tool_name`, `model` (optional), `input_tokens`, and `output_tokens`. Emits a budget warning notification if 80% of threshold is reached.\n\n### Budgets & routing (3 tools)\n\n- `set_budget_alert` — Set a budget threshold in USD (`threshold_usd`). Warns at 80% and 100% of the threshold. Use with `--enforce-budget` to block calls beyond the limit.\n- `suggest_model_routing` — Heuristic model recommendation by task type. Takes `task_description` and optional `constraints.max_cost_usd`. Returns recommended model with reasoning and estimated cost.\n- `check_routing_policy` — Check whether a model is allowed for a given task type under the routing policy. Takes `task_type` and `model`.\n\n### History & reports (4 tools)\n\n- `get_spend_history` — Query historical spend aggregated by `period` (`day`/`week`/`month`). Returns breakdown by model and tool. Read-only.\n- `estimate_workflow_cost` — Pre-run cost estimation for a multi-step workflow. Takes a `steps` array with `tool_name`, `estimated_input_tokens`, `estimated_output_tokens`, and optional `model`. Read-only.\n- `export_spend_report` — Generate a single-file HTML spend report with session breakdown, historical spend, model cost comparison, and budget status. Read-only.\n- `export_budget_audit` — Export the audit log of budget enforcement decisions. Accepts optional `from_date`, `to_date`, and `format` (`json`/`csv`). Read-only.\n\n### Project allocation (4 tools)\n\n- `set_project` — Create or update a project with an optional `budget_usd`. Takes `project_name`.\n- `tag_session` — Tag the current session with a `project_name` for cost allocation.\n- `get_project_costs` — Get cost report for a project. Takes `project_name` and optional `since` (ISO date). Read-only.\n- `export_chargeback` — Generate a chargeback report for internal billing. Takes `from_date`, `to_date`, optional `group_by` (`project`/`session`), and optional `format` (`json`/`csv`). Read-only.\n\n## Configuration\n\n### `--budget-alert`\n\nSession spend threshold in USD. A warning is returned when session costs reach 80% and again at 100% of this threshold.\n\nType: `number`\n\n### `--db` / `--db-path`\n\nPath to the SQLite database file used to store cost history.\n\nType: `string`\nDefault: `~/.mcp/costs.db`\n\n### `--pricing-table`\n\nPath to a JSON file containing custom model pricing ($/1K tokens). Merged with the built-in table; missing models fall back to defaults.\n\nType: `string`\n\n### `--default-model`\n\nModel name to attribute costs to when no model can be inferred from context.\n\nType: `string`\nDefault: `claude-sonnet-4-6`\n\n### `--enforce-budget`\n\nBlock tool calls that would cause the session to exceed the budget alert threshold. Requires `--budget-alert` to be set.\n\nType: `boolean`\nDefault: `false`\n\n### `--http-port`\n\nStart in HTTP mode using Streamable HTTP transport instead of stdio. Useful for sharing a single cost-tracking instance across a team.\n\nType: `number`\nDefault: disabled (uses stdio)\n\nPass flags via the `args` property in your JSON config:\n\n```json\n{\n  \"mcpServers\": {\n    \"cost-tracker\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"mcp-cost-tracker-router@latest\",\n        \"--budget-alert=2.00\",\n        \"--enforce-budget\"\n      ]\n    }\n  }\n}\n```\n\n## Supported models and pricing\n\nBuilt-in pricing table (USD per 1K tokens):\n\n| Model             | Input     | Output    |\n| ----------------- | --------- | --------- |\n| claude-opus-4-6   | $0.0150   | $0.0750   |\n| claude-sonnet-4-6 | $0.0030   | $0.0150   |\n| claude-haiku-4-5  | $0.0008   | $0.0040   |\n| gpt-4o            | $0.0025   | $0.0100   |\n| gpt-4o-mini       | $0.000150 | $0.000600 |\n| gemini-1.5-pro    | $0.001250 | $0.005000 |\n| gemini-1.5-flash  | $0.000075 | $0.000300 |\n| gemini-2.0-flash  | $0.000100 | $0.000400 |\n\nOverride individual model prices with `--pricing-table`. All costs are estimates.\n\n## Verification\n\nBefore publishing a new version, verify the server with MCP Inspector to confirm all tools are exposed correctly and the protocol handshake succeeds.\n\n**Interactive UI** (opens browser):\n\n```bash\nnpm run build && npm run inspect\n```\n\n**CLI mode** (scripted / CI-friendly):\n\n```bash\n# List all tools\nnpx @modelcontextprotocol/inspector --cli node dist/index.js --method tools/list\n\n# List resources and prompts\nnpx @modelcontextprotocol/inspector --cli node dist/index.js --method resources/list\nnpx @modelcontextprotocol/inspector --cli node dist/index.js --method prompts/list\n\n# Call a read-only tool\nnpx @modelcontextprotocol/inspector --cli node dist/index.js \\\n  --method tools/call --tool-name get_session_cost\n\n# Call record_usage with arguments\nnpx @modelcontextprotocol/inspector --cli node dist/index.js \\\n  --method tools/call --tool-name record_usage \\\n  --tool-arg tool_name=my_tool --tool-arg input_tokens=500 --tool-arg output_tokens=200\n```\n\nRun before publishing to catch regressions in tool registration and runtime startup.\n\n## Contributing\n\nUpdate `src/pricing.ts` when new models are released. All cost calculation changes must include unit tests with known token counts and expected USD values. Routing suggestions live in `src/tools/routing.ts`.\n\n```bash\nnpm install && npm test\n```\n\n## MCP Registry & Marketplace\n\nThis plugin is available on:\n\n- [MCP Registry](https://registry.modelcontextprotocol.io)\n- [MCP Market](https://mcpmarket.com)\n\nSearch for `mcp-cost-tracker-router`.\n",
  "bytes": 9549,
  "sha": "68865328b2cd320a4114ddb4c8efde01ff0847ad78bf486c3c414b5202843cc9",
  "repo_slug": "dbsectrainer/mcp-cost-tracker-router",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_dbsectrainer_mcp_cost_tracker__96cb099a/readme"
}