contextburn — Claude Code MCP server: how much of your spend was work
Reads the Claude transcripts already on your disk and reports what share of paid tokens turned into model output rather than context re-reading.
claude mcp add contextburn -- uvx contextburnWhat contextburn does
contextburn parses the session logs Claude leaves on your machine. What you get back is a share: how much of what you paid for came out as model output, and how much was the agent reading context it had already sent. A token counter tells you what you spent. This tells you how much of that was work.
There are two figures, and they behave differently. The token share barely moves between runs, since every agent step resends the accumulated context. The cost-weighted share does move, because cached reads are priced below fresh input and output, so it reflects how you run sessions. Per-model prices sit at the top of bin/contextburn and need updating by hand when they change.
The CLI is a single Python 3 file with no dependencies, copied into ~/bin. The MCP server speaks stdio and exposes two tools: run_efficiency for the shares as structured data, spend_breakdown for the full report. Only local transcripts under ~/.claude/projects/**/*.jsonl are read, and there are no network calls. Claude transcripts are the only source it handles for now, so there is nothing to count on other agents.
What it helps with
- see what share of paid tokens became model output
- spot how much context the agent re-reads
- compare one long session against several short ones
- let the agent check its own run efficiency mid-session
- watch the current token burn rate
Example prompts for the agent
- Show my run efficiency for the last 24 hours
- Break down what inflated the context in this session
- How many tokens went to re-reading versus output?
How to install contextburn
Platform CLI
claude mcp add contextburn -- uvx contextburnuvx runs the command named after the package; if the README names another one, use uvx --from contextburn <command>
Platform CLI
codex mcp add contextburn -- uvx contextburnuvx runs the command named after the package; if the README names another one, use uvx --from contextburn <command>
Config file
{
"mcpServers": {
"contextburn": {
"command": "uvx",
"args": [
"contextburn"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from contextburn <command>
Config file
{
"servers": {
"contextburn": {
"type": "stdio",
"command": "uvx",
"args": [
"contextburn"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from contextburn <command>
Platform CLI
gemini mcp add contextburn uvx contextburnuvx runs the command named after the package; if the README names another one, use uvx --from contextburn <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about contextburn
How do I install contextburn in Claude Code?
Run claude mcp add contextburn -- uvx contextburn. That registers the MCP server, and the agent then sees the run_efficiency and spend_breakdown tools.
What does contextburn do?
It reads local Claude transcripts and reports what share of paid tokens became model output. Two numbers come out: one by tokens, one weighted by cost.
Does it need an API key or network access?
No. It reads files under ~/.claude/projects/**/*.jsonl and sends nothing anywhere. The CLI needs Python 3 and nothing else.
