Skip to content
MCP server

AI Usage

See what your coding agent costs: token usage, cache breaks and budgets from local data

Runs locallyStatus and history
Install
Platforms
CLI
Runs
Locally
Version
0.17.1
Listing updated
today

Similar MCP servers

About AI Usage

AI Usage is an MCP server for developer tools. It runs locally on your machine and is started by your AI client.

This server answers cost questions from files that Claude Code, OpenCode and Codex CLI already wrote to your machine, with no upload, account or API key. Claude Code deletes transcripts after 30 days by default, so every turn is copied into a local SQLite database and history survives, and two machines can be merged into one total.

The cache_health tool finds turns where a session lost its cached prefix and re-wrote the whole context, names a likely cause such as a model switch or idling past the cache lifetime, and prices the extra cost. counterfactual_cost reprices the same tokens at another model's rates. It adds plan-limit tracking, budgets with forecasts, project and day breakdowns and CSV or JSON export.

It says it never fabricates numbers: if a source does not record a value it is reported as unavailable. A verify command re-reads the sources independently and diffs them against its own database. It needs Node 22.13 or later.

Install

Run in a terminal

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

Add to claude_desktop_config.json

{
  "mcpServers": {
    "ai-usage-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "ai-usage-mcp"
      ]
    }
  }
}
Install in CursorOpens Cursor, which asks you to confirm. Or add it by hand:

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "ai-usage-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "ai-usage-mcp"
      ]
    }
  }
}
Install in VS CodeOpens VS Code, which asks you to confirm. Or add it by hand:

Add to .vscode/mcp.json

{
  "servers": {
    "ai-usage-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "ai-usage-mcp"
      ]
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json

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

Add to your client's MCP settings (most use this shape)

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

Using several servers? Build one config file with the MCP config generator.

Tools this server provides (2)

Taken from the project documentation; the running server may differ.

cache_health
Finds turns where a session lost its cached prefix and prices the premium.
counterfactual_cost
Prices the same tokens at another model's rates.

What it does

Retained history
Copies turns to local SQLite so usage outlives transcript cleanup.
Cache-break finder
Locates and prices lost cached context.
Counterfactual pricing
Reprices past usage at another model's rates.
Self-verification
A second implementation checks totals against the database.
Budgets and exports
Run rate, forecasts and CSV or JSON output.

Good for

  • Find out why a session was expensive
  • Compare last week's cost on a cheaper model
  • Track spend per project per day
  • Check plan-limit usage

AI Usage FAQ

Does it upload anything?

No. It reads local files and needs no account or key.

Which agents does it read?

The README names Claude Code and OpenCode, and Codex CLI in its introduction.

Does it add reported and estimated cost together?

No. They are always kept separate.

What Node version?

22.13 or later.

How do I add AI Usage to Claude Code?

Run this command in your terminal: claude mcp add ai-usage-mcp -- npx -y ai-usage-mcp

What are the best alternatives to AI Usage?

The closest alternatives to AI Usage are REA, Context7, Chrome DevTools MCP, Codebase Memory and GitHub.

Where this comes from

  • Description: written from the project's README.
  • Install steps: from the official MCP Registry entry.

How AIPoweredBot checks servers