claude-code-usage-mcp

claude-code-usage-mcp

An MCP server that surfaces your Claude Code usage — today's token usage and estimated cost, plan-limit utilization (5-hour, weekly, and per-model weekly windows) with reset times and pace projection, recent burn rate, and current context-window fill. It reads Claude Code's local logs (~/.claude/projects) and Anthropic's OAuth usage endpoint, exposing the data as tools any MCP client can call.

Works in any MCP client — Zed, Claude Desktop, Cursor, Cline, and others.

Tools

• get_claude_usage — current snapshot: today's cost and tokens, plan-limit utilization with reset times and pace projection, burn rate, 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).

Requirements

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

Usage

Run it directly with npx:

npx -y claude-code-usage-mcp

Zed (settings.json)

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

Claude Desktop (claude_desktop_config.json)

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

Then ask the agent: "What's my Claude Code usage right now?"

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.

License

MIT — see the repository.