token-tracker-mcp

See where your AI tokens go — and how to spend less of them.

token-tracker-mcp is an MCP server + CLI that logs every Claude / GPT / Gemini API call locally, shows you a cost dashboard in your terminal, and — crucially — tells you exactly how to reduce that cost.

  ⬡ token-tracker  LAST 7 DAYS
────────────────────────────────────────────────────────────────────────────────

  Overview
  Total cost          $18.7421   (~$80.59/month est.)
  API calls           347
  Input tokens        4.82M
  Output tokens       692K
  Cache reads         620K  (11.4% hit rate)
  Avg cost/call       $0.0540

  Daily Cost                           7 days
  Mon Jun 02  ████████████░░░░░░░░░░░░   $2.1400
  Tue Jun 03  ████████████████████░░░░   $3.8200
  Wed Jun 04  ██████░░░░░░░░░░░░░░░░░░   $1.2000
  Thu Jun 05  ████████████████████████   $4.5100

  💡 Optimization Hints               saves $31.20/mo
  ● CRIT  Prompt cache barely used
          Move static content to the top of your messages…
          Evidence: Cache hit rate: 11.4% (620K cached vs 4.82M total input)

  ● HIGH  Expensive model doing test generation
          Route test-gen to claude-haiku-4-5. Saves 80% on those calls.

Install

# global install
npm install -g token-tracker-mcp

# or run without installing
npx token-tracker-mcp report

Connect to Claude Desktop

token-tracker setup

Or add manually to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "token-tracker": {
      "command": "token-tracker",
      "args": ["serve"]
    }
  }
}

Restart Claude Desktop. Done.

CLI Commands

| Command | Description | |---|---| | token-tracker report | Full 7-day dashboard (default) | | token-tracker report --period month | Monthly report | | token-tracker today | Today only | | token-tracker hints | All optimization hints, ranked by saving | | token-tracker hint cache-utilization | Deep-dive on one hint | | token-tracker status | One-line status: cost · cache % · top hint | | token-tracker budget | Budget gauges | | token-tracker models | Pricing table for all known models | | token-tracker export > usage.csv | Raw data export |

MCP Tools (use inside Claude)

| Tool | Description | |---|---| | log_usage | Log an API call with token counts — auto-calculates cost | | get_summary | Summary for today / week / month / all | | get_hints | Ranked optimization hints with $ savings | | get_hint_detail | Deep-dive on a specific hint | | set_budget | Set a daily / weekly / monthly spend limit | | list_sessions | Sessions ranked by cost | | list_models | Pricing table | | export_csv | CSV dump |

Optimization Hints (8 rules, zero LLM cost)

The hints engine is fully deterministic — no API calls, runs instantly on your local data.

| Hint ID | Triggers when | |---|---| | cache-utilization | Cache hit rate < 30% | | model-swap-testing | Test gen on Sonnet / Opus | | model-swap-debug | Debugging on Opus | | verbose-outputs | Output / input ratio > 0.35 | | session-spike | Any session costs 3× your average | | context-bloat | Avg tokens / call > 8K | | retry-loops | Sessions with 30+ high-token calls | | single-model-dependency | 100% traffic on one expensive model |

Each hint includes: severity · evidence · recommended action · estimated monthly saving.

Data & Privacy

All data is stored at ~/.token-tracker/usage.db (SQLite).
Nothing leaves your machine. No telemetry, no external calls, no account required.

Development

git clone https://github.com/yourusername/token-tracker-mcp
cd token-tracker-mcp
npm install
npm run dev          # watch mode

# run tests
npm test

# release
npm run release:patch   # 1.0.0 → 1.0.1
npm run release:minor   # 1.0.0 → 1.1.0

Roadmap

• [ ] Team / Supabase backend (multi-user shared dashboard)
• [ ] Weekly email digest
• [ ] Slack / webhook alerts
• [ ] macOS menubar app

License

MIT © 2026