AI Usage

ai-usage-mcp

Ask your coding agent what it has cost you — and where the money went. An MCP server that answers from the data Claude Code, OpenCode and Codex CLI already wrote to your machine. Nothing is uploaded, and there is no API key or account.

> Where are my tokens going, and what should I change?

Where did this session lose its prompt cache?

Which of my projects is getting more expensive, day by day?

What would last week have cost on Sonnet instead of Opus?

Three things it does that reading the transcripts cannot:

• It keeps your history. Claude Code deletes transcripts after 30 days (cleanupPeriodDays). Every turn is copied into a local SQLite database as it is seen, so last quarter is still there after the source files are gone — and merges two machines into one total.
• It finds where the cache broke. Cache tokens are where the money is — 94.7% of all tokens on the development machine. cache_health finds the turns where a session lost its cached prefix and paid to re-write the whole context, names the likely cause (a model switch, idling past the 5-minute TTL, an edited CLAUDE.md) and prices the premium.
• It proves its numbers. Claude Code writes one JSONL line _per content block_, each repeating the same usage object, so summing lines inflates every figure 2–3×. 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.

Also: your Pro/Max plan limits — the 5-hour and weekly percentages Claude Code reports, kept by a status line and projected to the time you would hit 100% — plus counterfactual_cost (these exact tokens at another model's rates), budgets with run rate and forecast, project × day breakdowns, and CSV/JSON export. It supports Claude Code and OpenCode, and exposes twelve MCP tools plus resources, prompts and a debug CLI that prints the same text the tools return.

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.

Try it in one command

There's nothing to configure and no account to create. It reads what Claude Code and OpenCode have already written to this machine:

npx -y -p ai-usage-mcp ai-usage report

The first run copies your history into a local database, which takes a few seconds. The report gives a verdict for the last 7 days, says where the tokens went, and lists what to change. To ask your agent questions like the ones above, install it as an MCP server.

ai-usage or ccusage?

ccusage is the established tool, and a good one: it covers far more agents, and its Claude Code token counts agree with this package's exactly — every token class, every day, checked against ccusage 20.0.26 on the development machine for 21–25 September 2026. For a quick report across many agents, use it.

Use this one when you want what a report over the current transcripts cannot give: history that outlives Claude Code's 30-day cleanup, cache breaks found and priced, counterfactual pricing, budgets, cross-dimension breakdowns, reported and estimated cost kept apart, and token totals proved against a second read by verify.

---

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

As a plugin — recommended. Run these two inside Claude Code:

/plugin marketplace add MohitBansal321/ai-usage-mcp

/plugin install ai-usage@ai-usage-mcp

That wires up the MCP server _and_ installs the three prompts as real slash commands — /ai-usage:daily-review, /ai-usage:why-was-today-expensive, /ai-usage:project-cost — which most clients never surface from MCP prompts alone. If the install summary says Run /reload-plugins to activate., run that. The equivalent from your shell is claude plugin marketplace add MohitBansal321/ai-usage-mcp.

The plugin declares npx -y ai-usage-mcp as its server, so the server itself still comes from npm and re-resolves on each cold start. Updating the plugin and updating the server are therefore independent — see Updating .

Or as a plain MCP server, if you would rather not add a marketplace. Nothing to install first — npx fetches it on demand:

claude mcp add ai-usage -s user -- npx -y ai-usage-mcp

On native Windows (not WSL), wrap it in cmd /c instead:

claude mcp add ai-usage -s user -- cmd /c npx -y ai-usage-mcp

Why: on Windows npx is npx.cmd, and the MCP TypeScript SDK spawns servers with shell: false . Node cannot execute a .cmd file that way — its docs say such files "can be invoked using child_process.spawn() with the shell option set … or by spawning cmd.exe and passing the .bat or .cmd file as an argument". cmd /c is that second form. This applies to every SDK-based client below, not just Claude Code.

-s user makes it available in every project. Drop it to add the server to the current project only. Then run /mcp inside Claude Code to confirm it connected.

No claude command? (VS Code / JetBrains extension users)

The extension reads the same configuration as the CLI, so you can add the server by editing a file — no CLI needed. Pick whichever scope you want:

For one project — create .mcp.json in the project root:

{

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

Claude Code asks you to approve a project-scoped server the first time it loads it. This file is safe to commit if you want your team to get it too.

For all your projects — add the same mcpServers block at the top level of ~/.claude.json (%USERPROFILE%\.claude.json on Windows):

{

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

That file already exists and holds other settings — add the mcpServers key alongside them rather than replacing the file.

Then reload the window (Developer: Reload Window in VS Code) and run /mcp. Configuration is read when a session starts, so an already-open session will not pick it up.

OpenCode

opencode mcp add ai-usage       # choose a local server, command: ai-usage-mcp

Or add it to ~/.config/opencode/opencode.jsonc:

{

"mcp": { "ai-usage": { "type": "local", "command": ["npx", "-y", "ai-usage-mcp"], }, }, }

Confirm with opencode mcp list.

Codex CLI

codex mcp add ai-usage -- npx -y ai-usage-mcp

Codex usage is read from ~/.codex/sessions (or $CODEX_HOME). Codex records no cost, so its cost is an API-equivalent estimate, or unavailable for a model the pricing table lacks. Support is new and verified against two sessions so far; ai-usage verify checks it on yours.

Other MCP clients

Cursor, Google Antigravity, Windsurf and Claude Desktop take the same npx -y ai-usage-mcp block; only the config file differs. The client you ask from does not have to be one you measure: ask from Cursor, and you still get your Claude Code numbers. Paths and details are in docs/INSTALL.md.

The debug CLI

The MCP server needs no install. To also get the ai-usage CLI on your PATH:

npm install -g ai-usage-mcp

ai-usage status

Or run it without installing:

npx -y -p ai-usage-mcp ai-usage stats --today

Windows: no longer needs a particular npm. The node-gyp failure that used to break

this install came from the native better-sqlite3 dependency, which is now optional and

unused on Node 22.13+. If npm still reports a build failure for it, that message is a

skipped optional dependency, not a failed install — ai-usage status will show

SQLite driver: node:sqlite and everything works.

Updating

npx -y ai-usage-mcp re-resolves the version on every cold start, so restarting your client picks up a release. A global install is pinned: npm install -g ai-usage-mcp@latest. ai-usage status and the MCP server both tell you when you are behind. docs/INSTALL.md says what each kind of install needs, and describes the one request the check makes.

Compatibility

Both source formats are internal and unversioned, so a client update can change them. This is what has been checked, and how:

"Verified" means ai-usage verify matched every token class exactly against an independent re-read of the