io.github.wheelbarrel00/claude-code-usage
Claude Code token usage, cost, and plan limits from local logs and Anthropic's usage API.
Open source Open in the app JSON README (API)
About
Claude Code token usage, cost, and plan limits from local logs and Anthropic's usage API.
Details
- Kind
- MCP servers
- Topic
- AI, RAG & memory
- Publisher
- wheelbarrel00
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.0
- Last push
- 2026-06-21T22:07:45Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 04:01:40
- Updated
- 2026-08-29 04:01:40
- Origin id
io.github.wheelbarrel00/claude-code-usage
README
# Claude Code Usage
[](https://www.npmjs.com/package/claude-code-usage-mcp)
[](https://registry.modelcontextprotocol.io)
[](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