claude-code-usage

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

Register it with your client. For Zed (settings.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