# AI Usage

> AI Usage is an MCP server for developer tools. See what your coding agent costs: token usage, cache breaks and budgets from local data. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Platforms:** CLI
- **Repository:** https://github.com/mohitbansal321/ai-usage-mcp
- **MCP Registry name:** io.github.MohitBansal321/ai-usage-mcp
- **Categories:** [developer tools](https://ai-powered.com/categories/developer-tools), [analytics and data](https://ai-powered.com/categories/analytics-and-data)
- **Listing updated:** 2026-11-18

## About

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.

## Features

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

## Install

### Claude Code (Terminal)

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

### Claude Desktop (claude_desktop_config.json)

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

### Cursor (~/.cursor/mcp.json)

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

### VS Code (.vscode/mcp.json)

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

### Windsurf (~/.codeium/windsurf/mcp_config.json)

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

### Other clients (your client's MCP settings (most use this shape))

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

## Tools

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

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

## Alternatives

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [Context7](https://ai-powered.com/mcp/context7): Context7 is a freemium MCP server for developer tools.
- [Chrome DevTools MCP](https://ai-powered.com/mcp/chrome-devtools-mcp-2): Chrome DevTools MCP is an open-source MCP server for browser automation.
- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [GitHub](https://ai-powered.com/mcp/github-2): GitHub is an open-source MCP server for developer tools.
- [Serena MCP: the IDE for your agent](https://ai-powered.com/mcp/serena-mcp-the-ide-for-your-agent): Serena MCP: the IDE for your agent is an open-source MCP server for developer tools.
- [awesome-mcp-servers](https://ai-powered.com/mcp/awesome-mcp-servers-2): awesome-mcp-servers is an open-source MCP server for developer tools.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.

---
Source: https://ai-powered.com/mcp/ai-usage
