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.

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 descending. Read-only.
• `reset_session` — Start a new cost-tracking session. Previous session data is retained in history.
• `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.

Budgets & routing (3 tools)

• `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.
• `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.
• `check_routing_policy` — Check whether a model is allowed for a given task type under the routing policy. Takes `task_type` and `model`.

History & reports (4 tools)

• `get_spend_history` — Query historical spend aggregated by `period` (`day`/`week`/`month`). Returns breakdown by model and tool. Read-only.
• `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.
• `export_spend_report` — Generate a single-file HTML spend report with session breakdown, historical spend, model cost comparison, and budget status. Read-only.
• `export_budget_audit` — Export the audit log of budget enforcement decisions. Accepts optional `from_date`, `to_date`, and `format` (`json`/`csv`). Read-only.

Project allocation (4 tools)

• `set_project` — Create or update a project with an optional `budget_usd`. Takes `project_name`.
• `tag_session` — Tag the current session with a `project_name` for cost allocation.
• `get_project_costs` — Get cost report for a project. Takes `project_name` and optional `since` (ISO date). Read-only.
• `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.

Configuration

`--budget-alert`

Session spend threshold in USD. A warning is returned when session costs reach 80% and again at 100% of this threshold.

Type: `number`

`--db` / `--db-path`

Path to the SQLite database file used to store cost history.

Type: `string`

Default: `~/.mcp/costs.db`

`--pricing-table`

Path to a JSON file containing custom model pricing ($/1K tokens). Merged with the built-in table; missing models fall back to defaults.

Type: `string`

`--default-model`

Model name to attribute costs to when no model can be inferred from context.

Type: `string`

Default: `claude-sonnet-4-6`

`--enforce-budget`

Block tool calls that would cause the session to exceed the budget alert threshold. Requires `--budget-alert` to be set.

Type: `boolean`

Default: `false`

`--http-port`

Start in HTTP mode using Streamable HTTP transport instead of stdio. Useful for sharing a single cost-tracking instance across a team.

Type: `number`

Default: disabled (uses stdio)

Pass flags via the `args` property in your JSON config:

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

Supported models and pricing

Built-in pricing table (USD per 1K tokens):

Override individual model prices with `--pricing-table`. All costs are estimates.

Verification

Before publishing a new version, verify the server with MCP Inspector to confirm all tools are exposed correctly and the protocol handshake succeeds.

Interactive UI (opens browser):

npm run build && npm run inspect

CLI mode (scripted / CI-friendly):

# List all tools
npx @modelcontextprotocol/inspector --cli node dist/index.js --method tools/list

# List resources and prompts
npx @modelcontextprotocol/inspector --cli node dist/index.js --method resources/list
npx @modelcontextprotocol/inspector --cli node dist/index.js --method prompts/list

# Call a read-only tool
npx @modelcontextprotocol/inspector --cli node dist/index.js \
  --method tools/call --tool-name get_session_cost

# Call record_usage with arguments
npx @modelcontextprotocol/inspector --cli node dist/index.js \
  --method tools/call --tool-name record_usage \
  --tool-arg tool_name=my_tool --tool-arg input_tokens=500 --tool-arg output_tokens=200

Run before publishing to catch regressions in tool registration and runtime startup.

Contributing

Update `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`.

npm install && npm test

MCP Registry & Marketplace

This plugin is available on:

• MCP Registry
• MCP Market

Search for `mcp-cost-tracker-router`.