AI Usage MCP server

ai-usage-mcp

<!-- mcp-name: io.github.MohitBansal321/ai-usage-mcp -->

Whatever is telling you what your coding agent costs is probably inflating it. Claude Code writes one JSONL line per content block, and every line repeats the same usage object with a cumulative outputtokens. Summing those lines — the obvious thing to do, and what naive tools do — inflated every figure by 2.15× to 3.05×** on the development machine: 1.79B cache-read tokens claimed where the truth was 800M.

Cache tokens are also where the money actually is. Cache-read outweighed input by roughly 33,000× (800,839,432 vs 24,381), so any tool that blends token classes into a single "total" has told you nothing you can act on.

This one reads the same files, deduplicates on requestId + message.id, and then proves it: ai-usage verify re-reads both sources with a second, independent implementation that shares no reduction code with the collectors, and diffs the result against its own database.

$ ai-usage verify

== claude-code ==
  MATCH    claude JSONL, deduped by stop_reason line (independent rule)
  INFO     claude JSONL, naive sum of every usage line (NOT used -- shows the double count)
           delta:  cache-read 990,824,820 ...

RESULT: every client reconciles exactly against at least one independent read of its source.

So the question it answers, from real data on your machine:

How many tokens have I used, from which client, model and session — and what did it cost?

Phase 1 supports two coding agents: Claude Code and OpenCode. It reads the data those clients already wrote to disk, normalises it into one schema, stores it in a local SQLite database, and exposes seven MCP tools -- plus resources, prompts and a debug CLI.

It never fabricates a number. If a source does not record something, it is reported as unavailable — not as zero.

What the output looks like (sample data)

$ ai-usage stats --today
Usage summary -- today (local time)
Subagent/sidechain turns: INCLUDED (3 main + 1 subagent turns).

Records: 4   Sessions: 2

Tokens (all clients):
  Input:        1,871
  Output:       16,909 (16.9K)
  Cache read:   2,452,000 (2.45M)
  Cache write:  37,300 (37.3K)
  Reasoning:    2,600
  Total:        2,508,080 (2.51M)

  Cost (reported by client, exact): $0.41  [1 records]
  Cost (estimated, API-equivalent):  $1.50  [3 records]

By client:
  claude-code  --  3 records, 1 sessions
    Cache read:   2,238,000 (2.24M)
    Total:        2,280,001 (2.28M)
    Cost (estimated, API-equivalent):  $1.50  [3 records]

  opencode  --  1 records, 1 sessions
    Cache read:   214,000 (214.0K)
    Total:        228,079 (228.1K)
    Cost (reported by client, exact): $0.41  [1 records]

The two cost lines are never added together, and never will be — see How cost is reported.

Install

Requires Node.js 22.13+. No compiler, build tools or particular npm version needed: storage uses Node's built-in node:sqlite, which is unflagged from 22.13.0 onward. There is no mandatory native dependency.

better-sqlite3 remains an optional fallback for hosts whose Node predates that. It is never required — if it cannot be built, npm skips it and the server still runs.

Claude Code

Shortened. The full README is on GitHub.