{
  "markdown": "# Claude Code Usage\n\n[![npm version](https://img.shields.io/npm/v/claude-code-usage-mcp.svg)](https://www.npmjs.com/package/claude-code-usage-mcp)\n[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-listed-0a7ea4.svg)](https://registry.modelcontextprotocol.io)\n[![License: MIT](https://img.shields.io/npm/l/claude-code-usage-mcp.svg)](https://github.com/wheelbarrel00/ClaudeCodeUsageTool/blob/main/LICENSE)\n\nAn MCP server that surfaces your Claude Code token usage, estimated cost, and\nplan-limit status in any MCP client (Zed, Claude Desktop, Cursor, and others). It\nreads Claude Code's own logs (`~/.claude/projects/**/*.jsonl`) and Anthropic's usage\nAPI, then exposes the data as tools the agent can call.\n\nPublished on npm as [`claude-code-usage-mcp`](https://www.npmjs.com/package/claude-code-usage-mcp)\nand in the [official MCP registry](https://registry.modelcontextprotocol.io) as\n`io.github.wheelbarrel00/claude-code-usage`.\n\n## What you get\n\nTwo tools:\n\n- **`get_claude_usage`** — today's cost and tokens, 5-hour and weekly plan-limit\n  utilization (with reset times and a pace projection), recent burn rate, current\n  context-window fill, and pay-as-you-go extra usage.\n- **`get_usage_breakdown`** — usage grouped by model, project, session, or git\n  branch, or over time (daily this month / monthly all-time).\n\nAsk the agent things like *\"what's my Claude usage right now?\"* or *\"break down my\nClaude spend by project this month.\"* MCP tools are queried on demand — there's no\npersistent status-bar display.\n\n## Install\n\n```sh\nnpx -y claude-code-usage-mcp\n```\n\nRegister it with your client. For **Zed** (`settings.json`):\n\n```json\n{\n  \"context_servers\": {\n    \"claude-code-usage\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"claude-code-usage-mcp\"]\n    }\n  }\n}\n```\n\nFor **Claude Desktop** (`claude_desktop_config.json`), use the same command under\n`\"mcpServers\"` instead of `\"context_servers\"`.\n\n## Requirements\n\nAn authenticated Claude Code install — the server reads `~/.claude/.credentials.json`\nand `~/.claude/projects`, the same files the CLI writes.\n\n## Configuration\n\nOptional environment variables:\n\n| Variable | Default | Meaning |\n|---|---|---|\n| `CCU_CURRENCY` | `USD` | ISO currency code for cost formatting. |\n| `CCU_DECIMALS` | `2` | Decimal places for cost figures. |\n| `CCU_USE_LIVE_API` | `true` | Fetch live limits from Anthropic; falls back to the on-disk cache. |\n| `CCU_LIVE_MIN_INTERVAL_SECONDS` | `180` | Minimum seconds between live usage requests. |\n| `CCU_BURN_WINDOW_MINUTES` | `15` | Trailing window for the burn-rate calculation. |\n| `CCU_PROJECT_GROUPING` | `git` | `git`, `folder`, or `flat` grouping for the project breakdown. |\n| `CLAUDE_CONFIG_DIR` | `~/.claude` | Override the Claude Code config directory. |\n\n## How it works\n\nLive plan limits come from `api.anthropic.com/api/oauth/usage` using the OAuth token\nalready on disk; the access token is refreshed in memory only, so a running Claude\nCode session is never logged out. Token and cost figures are parsed from the local\nsession logs.\n\n## Repository layout\n\n- `mcp-server/` — the MCP server (TypeScript, bundled to `dist/server.mjs`).\n- `extension.toml`, `Cargo.toml`, `src/lib.rs` — a self-contained Zed extension that\n  embeds and launches the server (an alternative to the `npx` install above).\n\n## Build from source\n\n```sh\ncd mcp-server\nnpm install\nnpm run build      # bundles to dist/server.mjs\nnode dist/server.mjs --selftest\n```\n\n### Zed extension (self-contained, no npm needed)\n\nThe Zed extension embeds the bundled server and launches it with Zed's own Node.\nBuild the server first, install [rustup](https://rustup.rs) and the WebAssembly\ntarget (`rustup target add wasm32-wasip1`), then in Zed open **Extensions → Install\nDev Extension** and select this repository's root folder.\n\n## License\n\nMIT\n",
  "bytes": 3826,
  "sha": "7d2c8209d814c1152fcd79ab1187853ec1619d82bd34a56dc2cf3df40572d8a9",
  "repo_slug": "wheelbarrel00/claudecodeusagetool",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_wheelbarrel00_claude_code_usag_fd734264/readme"
}