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.