Claude Usage MCP server

claudeusage

Measure whether your Claude subscription is actually paying off — from local logs, with no upload and no Git integration.

한국어 문서: README.ko.md — the Korean version is the working notebook, with the full measurements and the mistakes we made getting there.

Why this exists

On a subscription you don't pay per token, so nothing tells you whether you are using it well. Existing personal tools count how much you used. That is the wrong number: burning tokens in circles scores high. Meta ran an internal leaderboard like that and shut it down — people started idling AI to climb it.

Tools that measure quality do exist, but they are all built for teams: they need your Git repo, your PRs, your issue tracker. That leaves a gap.

Git-based tools track code with git blame, so anything you never committed is invisible to them. This reconstructs the edit history itself, so experiments and code you rewrote before committing still count.

What it measures

Lines that survived. Every edit is folded in time order, so only what was still there at the end of the session counts. Code you rewrote three turns later drops out by itself. You cannot game the score by idling.

Waste, in money. Rework, failures and rejections add up to 4.1% here. Money spent because conversations got long: 12.3%. So the useful advice is not "make fewer mistakes" — it's "start fresh conversations more often."

What the rate limit actually eats. Your real constraint is the limit gauge, not dollars. Cache reads are most of the cost but weigh about 1/70 of fresh input against the limit. Saving money and saving limit are different skills.

What chat ate. Limits apply to the whole account, so claude.ai chat and the mobile app drain the same gauge — while leaving no local trace. Any log-only tool undercounts. This one subtracts what the logs explain from what the gauge actually did, and checks that estimate against the per-product breakdown Anthropic returns.

Install

Requires Python 3.9+ (standard library only, no dependencies) and macOS for the live-limit tool.

git clone https://github.com/syk8015/claudeusage && cd claudeusage
./install.sh                   # package + skill + MCP server (user scope)
claude mcp list                # claudeusage … ✔ Connected

install.sh installs the package (trying uv, pipx, pip, then a dedicated venv — modern Pythons block system installs), drops the Claude Code skill in ~/.claude/skills/, and registers the MCP server. ./install.sh --uninstall reverses it.

That gives you the claudeusage command and the claudeusage-mcp server. A PyPI release (pip install claudeusage) is built and tested but not published yet.

One more step for the limit tools

Claude Code shows your limit gauge and throws it away — nothing stores it. claudeusage limit and claudeusage chat need that history, so a collector has to sit on your status line. Add this to ~/.claude/settings.json:

"statusLine": {
  "type": "command",
  "command": "claudeusage statusline --print"
}

Already have a status line you like? Drop --print and pipe into it — the collector passes the JSON straight through:

"command": "claudeusage statusline | bash ~/.claude/my-statusline.sh"

Nothing edits your settings for you — your status line is yours.

claudeusage value and claudeusage usage work right away, with no collector. The limit analysis gets useful after a few days of samples.

Shortened. The full README is on GitHub.