MCP Cost Tracker & Router

npm mcp-cost-tracker-router package

Local-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.

Tool reference | Configuration | Contributing | Troubleshooting

Key features

• Per-tool cost breakdown: See exactly which tool calls are consuming the most tokens and budget.
• Budget alerts: Set a session spend threshold and get warned at 80% and 100% before you exceed it.
• Offline token counting: Uses js-tiktoken for accurate counts — no API calls required.
• Model routing suggestions: Recommends cheaper models for the current task type (advisory, never enforced without opt-in).
• Multi-provider pricing: Tracks costs across Claude, OpenAI, and Gemini models from a single configurable pricing table.
• Spend history: Query daily, weekly, and monthly totals by model or tool.
• Project cost allocation: Tag sessions to named projects and generate chargeback reports.
• HTML spend reports: Export a single-file, self-contained HTML report with charts and budget status.
• Audit log: Append-only log of every budget enforcement decision.

Why this over proxy-based cost trackers?

Most 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.

| | mcp-cost-tracker-router | Proxy-based trackers (Helicone, LLMonitor, etc.) | | ----------------- | ------------------------------------------- | ------------------------------------------------ | | Token counting | Offline via js-tiktoken — no network call | Counted server-side after traffic is proxied | | Data residency | Local SQLite only | Prompts + responses pass through vendor servers | | Model routing | Built-in suggest_model_routing tool | Rarely included; usually a separate paid tier | | Multi-provider | Claude, OpenAI, Gemini in one pricing table | Often single-provider or requires separate setup | | Uptime dependency | None — fully offline | Breaks if proxy is down |

If 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.

Disclaimers

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.

Requirements

• Node.js v20.19 or newer.
• npm.

Getting started

Add the following config to your MCP client:

{
  "mcpServers": {
    "cost-tracker": {
      "command": "npx",
      "args": ["-y", "mcp-cost-tracker-router@latest"]
    }
  }
}

To set a session budget alert:

{
  "mcpServers": {
    "cost-tracker": {
      "command": "npx",
      "args": ["-y", "mcp-cost-tracker-router@latest", "--budget-alert=5.00"]
    }
  }
}

MCP Client configuration

Amp · Claude Code · Cline · Cursor · VS Code · Windsurf · Zed

Your first prompt

Enter the following in your MCP client to verify everything is working:

How much has this session cost so far?

Your client should return a token and USD cost summary for the current session.

Tools

Session (4 tools)

• get_session_cost — Returns token totals and USD cost estimates for the current session. Read-only.
• get_tool_costs — Returns per-tool cost breakdown for the session, sorted by cost des

... View full README on GitHub