MCP

Let your LLM read its own usage.

ccgauge ships a Model Context Protocol server: ccgauge mcp. Wire it into Claude Desktop, Cursor, Cline — or any MCP-compatible client — and ask the model: "how much did Opus cost me this week?" No screenshots, no SQL, no copy-paste.

1. Add it to your MCP client

Two config blocks below cover ~95 % of MCP-aware tools. The transport is stdio JSON-RPC — no port, no socket file. Any client that knows MCP knows how to read this.

Claude Desktop · ~/Library/Application Support/Claude/claude_desktop_config.json

json

{
  "mcpServers": {
    "ccgauge": {
      "command": "npx",
      "args": ["-y", "ccgauge", "mcp"]
    }
  }
}

Cursor · ~/.cursor/mcp.json

json

{
  "mcp": {
    "servers": {
      "ccgauge": {
        "command": "npx",
        "args": ["-y", "ccgauge", "mcp"]
      }
    }
  }
}

Restart the client. ccgauge should show up in the MCP tool picker with eight tools available. The server starts on first request and indexes your JSONL into a separate cache file (~/.ccgauge/cache/index-mcp-v2.json) so it never contends with the dashboard for the same on-disk index.

2. The eight tools

Each tool returns structured JSON. The LLM picks the right one based on your question; you don't need to remember names.

usage_summary

Totals (tokens, cost, cache savings, requests) over a range. Filter by source / models / projects.

usage_by_time

Time-bucketed series (hour / day / week / month) of tokens and cost.

usage_by_model

Per-model token + cost rollup with share-of-total.

usage_by_project

Per-cwd token + cost rollup. Worktree-aware project names.

usage_by_session

Per-session breakdown with title, model mix, duration, and cost.

daily_summary

A specific day's totals + top models + top projects. Useful for end-of-day reflection.

weekly_summary

A specific week's totals + day-by-day breakdown.

recent_activity

The last N assistant calls with timestamp / model / prompt preview / cost.

3. What to ask

Phrasing matters less than you'd think — the model translates plain English questions into MCP tool calls. A few starting points:

"How much did I spend on Opus this week, broken down by project?"

Uses: usage_by_project + filter by model
"Show me my Codex CLI usage for May 2026 as a daily chart."

Uses: usage_by_time with source=codex, gran=day
"Which sessions today used the most reasoning tokens?"

Uses: usage_by_session ordered by reasoning_tokens
"What did I work on between 9pm and midnight last Wednesday?"

Uses: recent_activity in a tight window
"Has my prompt-caching savings improved month over month?"

Uses: daily_summary then weekly_summary deltas
"Summarize my AI coding budget this month so I can put it in a doc."

Uses: usage_summary with range=current month

Notes

Still 100 % local. The MCP server reads the same JSONL the dashboard reads. The LLM client sends queries over stdio to a child process; nothing leaves your machine until the LLM itself answers you over its own provider connection.
Zombie processes can pollute cache. If you ever see "dashboard data looks stale", run ps -ef | grep ccgauge and kill any orphaned MCP processes. Each client is supposed to shut its server down on exit, but if a client crashes the child can linger and keep writing to the cache.
Reasoning tokens are surfaced for the models that emit them (most OpenAI o-series and recent GPT models). They appear as a separate field in usage_summary output.

← Back to features