Carbon Tracking MCP

MCP servers that estimate the energy used by your Claude Code and Codex sessions, so you can ask for it directly from within a chat: "how much energy has this chat used?" or "how much has this whole project cost?"

They wrap a small pricing-ratio energy model (src/mcps/energy_estimate.py) around each tool's local session logs — no telemetry, no network calls. The Claude Code server reads ~/.claude/projects/**/*.jsonl; the Codex server reads Codex's local thread index (~/.codex/state_5.sqlite) and rollout logs under ~/.codex/sessions/. Both run over the stdio MCP transport (src/mcps/stdio/), spawned fresh per chat by Claude Code/Codex.

What it does

Each server exposes the same two MCP tools, scoped to its own provider:

Example output:

{
  "session_id": "afc721a3-0d77-4c5f-b1f5-24074d03fa7d",
  "file": "/Users/you/.claude/projects/-Users-you-my-project/afc721a3-....jsonl",
  "request_count": 60,
  "estimated_kwh": 1.018,
  "estimated_kg_co2": 0.144,
  "comparisons": [
    {"id": "washing_machine_cycle", "label": "washing machine cycle", "count": 0.14},
    {"id": "kettle_boil", "label": "kettle boil", "count": 1.44}
  ]
}

{
  "project_dir": "/Users/you/.claude/projects/-Users-you-my-project",
  "session_count": 3,
  "total_estimated_kwh": 1.545,
  "sessions": [
    {"session_id": "afc721a3-...", "request_count": 60, "estimated_kwh": 1.018},
    {"session_id": "8ee8cb6f-...", "request_count": 5, "estimated_kwh": 0.073},
    {"session_id": "2aabc643-...", "request_count": 38, "estimated_kwh": 0.86}
  ],
  "estimated_kg_co2": 0.218,
  "comparisons": [
    {"id": "washing_machine_cycle", "label": "washing machine cycle", "count": 0.22}
  ]
}

estimated_kg_co2 and comparisons (both tools' full comparison list is longer than shown above — see carbon_equivalents.json) convert the estimated energy into CO2eq using a rough UK grid carbon intensity figure, then express it against everyday activities (washing machine cycles, EV charges, flights, ...). See "CO2eq comparisons" below.

Both tools return a typed, field-described pydantic model (src/mcps/schema.py), so MCP clients get a real JSON schema for the response shape rather than an untyped object. If a session/project can't be found, the tool raises a proper MCP tool error instead of returning a disguised "successful" result.

On the Claude Code server, current_session_energy identifies "this chat" via the CLAUDE_CODE_SESSION_ID environment variable that Claude Code sets on every process it launches (including the server). On the Codex server, it's identified via the CODEX_THREAD_ID environment variable, resolved to a rollout file through Codex's state_5.sqlite thread index (falling back to a filename scan under ~/.codex/sessions/ if the thread isn't indexed). Either tool's collate_project_sessions_energy then sums every other session belonging to the current project — every sibling .jsonl for Claude Code, every indexed thread with a matching cwd for Codex.

Related MCP server: Regen Compute

Install

Requires uv.

git clone https://github.com/<you>/carbon-tracking-mcp.git
cd carbon-tracking-mcp
uv sync

This installs console-script entry points (carbon-tracking-stdio-claude, carbon-tracking-stdio-codex) backed by the mcps package under src/.

Register whichever server(s) you use globally, so they're available in every project rather than just this one.

Claude Code

claude mcp add --scope user carbon-tracking-energy-claude -- uv run --directory /path/to/carbon-tracking-mcp carbon-tracking-stdio-claude

Restart or start a new session and the tools become available. Verify with:

claude mcp get carbon-tracking-energy-claude

Codex

codex mcp add carbon-tracking-energy-codex -- uv run --directory /path/to/carbon-tracking-mcp carbon-tracking-stdio-codex

codex mcp add writes to ~/.codex/config.toml, which Codex CLI, the IDE extension, and the desktop app all share — there's no per-project scope to choose, so this is global by default. Restart or start a new session and check /mcp inside Codex to verify the server is connected. Alternatively, add the entry by hand:

[mcp_servers.carbon-tracking-energy-codex]
command = "uv"
args = ["run", "--directory", "/path/to/carbon-tracking-mcp", "carbon-tracking-stdio-codex"]

Standalone CLI

src/mcps/energy_estimate.py also works as a plain script, independent of MCP:

uv run carbon-tracking-energy-estimate ~/.claude/projects/<project>/<session-id>.jsonl

60 deduplicated requests
Estimated session energy: 1.0181 kWh

The energy model

Follows Simon P. Couch's methodology: Wh-per-million-tokens rates are estimated from Epoch AI's ChatGPT-4o energy figures, using the price ratio between input/output/cache tokens as a proxy for their energy ratio (Anthropic doesn't publish energy numbers directly). This module uses the 500K-token context anchor point as a fixed rate for every request — see the docstring in energy_estimate.py for the full anchor table and derivation.

Read this before trusting the numbers:

• "Energy scales with price" is an assumption, not a measurement.

• Cache-read/cache-write rates are a flat napkin-math ratio applied to the input rate, not real per-model pricing.

• A single fixed rate is used for every request regardless of its actual context length, so short requests are overestimated and very long ones (near 1M tokens) are underestimated relative to a context-scaled model.

Treat every number here as order-of-magnitude and directional — useful for comparing sessions against each other, not as an audited carbon/energy figure.

CO2eq comparisons

carbon_equivalents.py converts an energy estimate (Wh) into kgCO2eq using a grid carbon intensity figure (default: a 2026 UK grid average of 141 gCO2/kWh, from Purely Energy's 2026 grid report) and expresses that total against everyday activities defined in carbon_equivalents.json — washing machine cycles, EV charges, flights, a kg of beef, and so on. Entries in that file are either kwh (converted through the grid intensity) or a direct kg_co2 figure for things that aren't grid electricity (car miles, flights, food).

Same caveat as above: this is a rough, directional comparison, not an audited figure — grid intensity varies by country, time of day, and year.

Project layout

src/mcps/
  schema.py                # pydantic models (with field descriptions) for every tool input/output
  energy_estimate.py       # the energy model + Claude Code/Codex session-log parsers (also runnable as a CLI)
  carbon_equivalents.py    # Wh -> kgCO2eq conversion + everyday-activity comparisons
  carbon_equivalents.json  # the comparison database (grid intensity + activity list)
  mcp_results.py           # shared MCP tool-result shaping used by every server below
  claude_sessions.py       # Claude Code session discovery (glob under ~/.claude/projects)
  codex_sessions.py        # Codex session discovery (sqlite thread index + ~/.codex/sessions)
  stdio/
    server_claude.py       # FastMCP server for Claude Code sessions
    server_codex.py        # FastMCP server for Codex sessions

License

MIT