# Claude Code Usage

[![npm version](https://img.shields.io/npm/v/claude-code-usage-mcp.svg)](https://www.npmjs.com/package/claude-code-usage-mcp)
[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-listed-0a7ea4.svg)](https://registry.modelcontextprotocol.io)
[![License: MIT](https://img.shields.io/npm/l/claude-code-usage-mcp.svg)](https://github.com/wheelbarrel00/ClaudeCodeUsageTool/blob/main/LICENSE)

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`](https://www.npmjs.com/package/claude-code-usage-mcp)
and in the [official MCP registry](https://registry.modelcontextprotocol.io) 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

```sh
npx -y claude-code-usage-mcp
```

Register it with your client. For **Zed** (`settings.json`):

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

```sh
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](https://rustup.rs) 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