Green MCP server

Green Agent

<!-- mcp-name: io.github.rlawogh1005/green-mcp -->

A pluggable MCP server that measures two efficiency axes of a program and refactors it to be cheaper while preserving behavior:

(AMD uProf / Linux RAPL / macOS powermetrics), chosen automatically for the host.

• CPU energy — joules the code actually consumes, from real hardware telemetry

measured provider-neutrally and non-blockingly.

• LLM tokens — the token usage of a program that calls LLMs (input/output/cache/reasoning),

Defining principle: measure, never estimate. Every claim is a measurement with the command, the number, and its run-to-run uncertainty — or it's labeled an estimate. The comparison verdict is a real statistical test (Welch's t with the idle-baseline uncertainty folded in), not a heuristic.

Quick start

pipx install green-mcp        # provides the `green-mcp` command (stdlib + mcp only)

Mount it in your IDE (configs in deploy/):

Then ask your agent to measure or compare energy/tokens of a command. See deploy/README.md for the full mount + harness guide.

Tools

measureenergy · compareenergy · measuretokens · comparetokens · verifyequivalence · energybackend_info

Requirements (what each part needs to actually work)

No server to host. green-mcp is not a web service — your IDE launches it as a local stdio subprocess. There's no cloud, no account, and no LLM key needed for the measurement server itself.

Energy axis — needs a power-sensor backend on the host (the largest prerequisite):

some distros.

• Windows + AMD → install AMD uProf separately (driver-based; admin to install). Not bundled.
• Linux → reads /sys/class/powercap (RAPL); no extra install, but energy_uj is root-only on

energyavailable: false and refuse to estimate. Energy generally does NOT work in Docker/CI** — containers and VMs have no power-sensor passthrough. Use the token axis there.

• macOS → uses the built-in powermetrics, which requires root / passwordless sudo.
• No reachable sensor (a VM, a container, a locked-down machine) → energy tools report

• The measured command runs locally (arbitrary commands → use in a trusted environment only).

Token axis — no special hardware, works anywhere, but:

OPENAIBASEURL, …) so we can route it through the counting proxy. A hardcoded endpoint won't be measured (reports 0 calls).

• The target program must read its LLM endpoint from an env var (ANTHROPICBASEURL,

target's API key is billed as usual, and network access to the provider is required.

• Measuring runs the target's real LLM calls — the proxy forwards to the real provider, so the

Bundled agent (optional) — pip install green-mcp[agent] adds the Claude Agent SDK and needs Anthropic credentials. The MCP server alone needs none.

Honest scope

written and unit-tested but unverified on metal, and no backend is yet cross-validated against a wall power meter. The token measurer is validated against a live provider (NVIDIA NIM, OpenAI-compatible: 5 real calls, streaming and non-streaming, matching the provider's own usage records exactly) — but the Anthropic-shaped usage path and rate-limit behavior are still only exercised against a local fake upstream. These gaps are tracked, not hidden.

• Energy is CPU package energy (+DRAM on RAPL) — not carbon, not whole-system.
• Numbers from different backends are not comparable.
• Only the AMD/uProf backend is validated for repeatability on real hardware; Linux/macOS are

Development

Shortened. The full README is on GitHub.