ai-usage-mcp

A local-first MCP server that 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.

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

Nothing to install first — npx fetches it on demand:

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

-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.

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

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

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.

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.

Verified against Claude Code 2.1.251 and OpenCode 1.18.25.

Updating

npx -y ai-usage-mcp — the form the instructions above use — re-resolves the version every time your client cold-starts the server, so it keeps itself current. Restart the client to pick up a new release.

A global install is pinned until you update it by hand:

npm install -g ai-usage-mcp@latest
ai-usage --version

ai-usage status tells you when you are behind:

Update available: 0.1.0 installed, 0.2.0 latest -- npm i -g ai-usage-mcp@latest

The MCP server says so too, because most people never run the CLI. When the server finds a newer release it says it once per process, through whichever channel comes first: a line added to the instructions it returns at handshake time, or a one-off note attached to the next tool result. It is a separate content block, so the numbers a tool returns stay exactly what the CLI prints for the same query, and it never repeats itself on later calls. The same line goes to the server's stderr log, and @usage://status shows the state on demand.

The advice differs by how you installed it, and the notice says the right one:

That check is the only network call in the package: a version lookup against the npm registry, at most once a day, cached in <config dir>/update-check.json, skipped when CI is set, and silently abandoned after 1.5s if you are offline. It sends no usage data and no identifier -- just a GET for a version string. Set AI_USAGE_NO_UPDATE_CHECK=1 to turn it off everywhere, CLI and server alike. In the server it runs after the handshake, never during it, so it cannot slow down a client starting up.

Ask it things

Once connected, ask in plain language:

How many tokens have I used today?
Show my usage for this session.
Which model consumed the most tokens?
How much did Claude Code cost me today?
Show all usage from the last 7 days.
Which repository is my spend going to?
Break my last 7 days down day by day.

MCP tools

Every period-based tool takes projectPath to narrow the report to one project.

Resources and prompts

Three resources can be pulled into a conversation with an @ mention, instead of asking for a tool call:

Three prompts appear as slash commands in a client that surfaces them:

Each prompt names the tools to call and carries the reported-vs-estimated cost rule with it, so a paraphrased summary cannot quietly merge the two cost bases.

Debug CLI

Same service layer, different frontend — so the two can never disagree.

ai-usage status      # collectors, data stores, db path, record counts, last sync
ai-usage sync        # run the collectors
ai-usage stats       # totals   (--today, --days N, --since/--until)
ai-usage models      # per-model
ai-usage clients     # per-client
ai-usage projects    # per-project  (--limit N)
ai-usage sessions    # recent sessions
ai-usage session ID  # one session in detail
ai-usage daily       # per-day breakdown
ai-usage verify      # re-read the sources and diff them against the local database

Add --json to any command for machine-readable output, and --project <path> to any period-based command to restrict it to one project.

ai-usage stats --today returns exactly what the usage_summary tool returns; a test in tests/mcp/parity.test.ts asserts they are byte-identical.

How cost is reported

Cost is never a single blended number. Every figure carries a basis: