io.github.wheelbarrel00/claude-code-usage

Official

by wheelbarrel00 · TypeScript

Claude Code token usage, cost, and plan limits from local logs and Anthropic's usage API.

Track Claude Code token usage, costs, and plan limits from logs and Anthropic API.

Claude Code Usage

An MCP server that surfaces your Claude Code token usage, estimated cost, and plan-limit status in any MCP client (Zed, Claude Desktop, Cursor, and others). It reads Claude Code's own logs (~/.claude/projects/**/*.jsonl) and Anthropic's usage API, then exposes the data as tools the agent can call.

Published on npm as claude-code-usage-mcp and in the official MCP registry as io.github.wheelbarrel00/claude-code-usage.

What you get

Two tools:

get_claude_usage — today's cost and tokens, 5-hour and weekly plan-limit utilization (with reset times and a pace projection), recent burn rate, current context-window fill, and pay-as-you-go extra usage.
get_usage_breakdown — usage grouped by model, project, session, or git branch, or over time (daily this month / monthly all-time).

Ask the agent things like "what's my Claude usage right now?" or "break down my Claude spend by project this month." MCP tools are queried on demand — there's no persistent status-bar display.

Install

npx -y claude-code-usage-mcp

json

{
  "context_servers": {
    "claude-code-usage": {
      "command": "npx",
      "args": ["-y", "claude-code-usage-mcp"]
    }
  }
}

For Claude Desktop (claude_desktop_config.json), use the same command under "mcpServers" instead of "context_servers".

Requirements

An authenticated Claude Code install — the server reads ~/.claude/.credentials.json and ~/.claude/projects, the same files the CLI writes.

Configuration

Optional environment variables:

Variable	Default	Meaning
`CCU_CURRENCY`	`USD`	ISO currency code for cost formatting.
`CCU_DECIMALS`	`2`	Decimal places for cost figures.
`CCU_USE_LIVE_API`	`true`	Fetch live limits from Anthropic; falls back to the on-disk cache.
`CCU_LIVE_MIN_INTERVAL_SECONDS`	`180`	Minimum seconds between live usage requests.
`CCU_BURN_WINDOW_MINUTES`	`15`	Trailing window for the burn-rate calculation.
`CCU_PROJECT_GROUPING`	`git`	`git`, `folder`, or `flat` grouping for the project breakdown.
`CLAUDE_CONFIG_DIR`	`~/.claude`	Override the Claude Code config directory.

How it works

Live plan limits come from api.anthropic.com/api/oauth/usage using the OAuth token already on disk; the access token is refreshed in memory only, so a running Claude Code session is never logged out. Token and cost figures are parsed from the local session logs.

Repository layout

mcp-server/ — the MCP server (TypeScript, bundled to dist/server.mjs).
extension.toml, Cargo.toml, src/lib.rs — a self-contained Zed extension that embeds and launches the server (an alternative to the npx install above).

Build from source

cd mcp-server
npm install
npm run build      # bundles to dist/server.mjs
node dist/server.mjs --selftest

Zed extension (self-contained, no npm needed)

The Zed extension embeds the bundled server and launches it with Zed's own Node. Build the server first, install rustup and the WebAssembly target (rustup target add wasm32-wasip1), then in Zed open Extensions → Install Dev Extension and select this repository's root folder.

License

MIT

Install

claude_desktop_config.json

{
  "mcpServers": {
    "claude-code-usage": {
      "command": "npx",
      "args": [
        "-y",
        "claude-code-usage-mcp@0.1.0"
      ]
    }
  }
}