Claude Code Usage MCP server

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:

utilization (with reset times and a pace projection), recent burn rate, current context-window fill, and pay-as-you-go extra usage.

• getclaudeusage — today's cost and tokens, 5-hour and weekly plan-limit

branch, or over time (daily this month / monthly all-time).

• getusagebreakdown — usage grouped by model, project, session, or git

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 (claudedesktopconfig.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:

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

embeds and launches the server (an alternative to the npx install above).

• mcp-server/ — the MCP server (TypeScript, bundled to dist/server.mjs).
• extension.toml, Cargo.toml, src/lib.rs — a self-contained Zed extension that

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