AI Usage
See what your coding agent costs: token usage, cache breaks and budgets from local data
- 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-mcpAdd to claude_desktop_config.json
{
"mcpServers": {
"ai-usage-mcp": {
"command": "npx",
"args": [
"-y",
"ai-usage-mcp"
]
}
}
}Add to ~/.cursor/mcp.json
{
"mcpServers": {
"ai-usage-mcp": {
"command": "npx",
"args": [
"-y",
"ai-usage-mcp"
]
}
}
}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.


