A
licenseB
qualityF
maintenanceTrack LLM token costs across Claude, GPT and Gemini. MCP server + CLI with optimization hints and $ savings estimates.
8
15
1
MIT
green-mcp
by rlawogh1005
The green-mcp server is a local agent that measures and compares the CPU energy consumption and LLM token usage of programs, helping you refactor for efficiency while verifying behavioral equivalence. Its capabilities include:
Measure energy of a shell command (CPU package energy in joules), with repeated runs and statistical reporting (mean, standard deviation, coefficient of variation) for reliability.
Compare energy consumption of two shell commands to determine which is more efficient and by what margin.
Check energy backend availability on the host (e.g., AMD uProf, Linux RAPL, macOS powermetrics) before attempting measurements.
Verify equivalence of two commands by comparing their stdout and exit codes, optionally with a battery of stdin inputs to ensure functional parity.
Measure LLM token usage (input, output, cache, reasoning, and total tokens) of a program via a transparent counting proxy, without requiring special hardware.
Compare LLM token usage between two programs to find the more token-efficient one.
Allows measuring CPU energy consumption using AMD uProf on Windows systems with AMD processors.
Allows measuring CPU and DRAM energy consumption via the Linux RAPL interface (requires root on some distros).
Allows measuring energy consumption using the built-in powermetrics tool (requires passwordless sudo).
Allows measuring token usage of programs that call OpenAI's API.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@green-mcpmeasure energy of 'python script.py'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Green Agent
A pluggable MCP server that measures two efficiency axes of a program and refactors it to be cheaper while preserving behavior:
CPU energy — joules the code actually consumes, from real hardware telemetry (AMD uProf / Linux RAPL / macOS powermetrics), chosen automatically for the host.
LLM tokens — the token usage of a program that calls LLMs (input/output/cache/reasoning), measured provider-neutrally and non-blockingly.
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/):
IDE | File |
Claude Code |
|
Cursor |
|
OpenAI Codex |
|
Google Antigravity |
|
Then ask your agent to measure or compare energy/tokens of a command. See
deploy/README.md for the full mount + harness guide.
Related MCP server: agent-cost-mcp
Tools
measure_energy · compare_energy · measure_tokens · compare_tokens ·
verify_equivalence · energy_backend_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.
To run the server | Python 3.10+, |
Energy axis — needs a power-sensor backend on the host (the largest prerequisite):
Windows + AMD → install AMD uProf separately (driver-based; admin to install). Not bundled.
Linux → reads
/sys/class/powercap(RAPL); no extra install, butenergy_ujis root-only on some distros.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
energy_available: falseand refuse to estimate. Energy generally does NOT work in Docker/CI — containers and VMs have no power-sensor passthrough. Use the token axis there.The measured command runs locally (arbitrary commands → use in a trusted environment only).
Token axis — no special hardware, works anywhere, but:
The target program must read its LLM endpoint from an env var (
ANTHROPIC_BASE_URL,OPENAI_BASE_URL, …) so we can route it through the counting proxy. A hardcoded endpoint won't be measured (reports 0 calls).Measuring runs the target's real LLM calls — the proxy forwards to the real provider, so the target's API key is billed as usual, and network access to the provider is required.
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
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 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
usagepath and rate-limit behavior are still only exercised against a local fake upstream. These gaps are tracked, not hidden.
Development
python -m venv .venv && .venv/Scripts/pip install -e ".[dev]"
.venv/Scripts/python -m pytest -q # unit tests
.venv/Scripts/python -m pytest -m integration # real-hardware (needs AMD uProf)Architecture and decisions live in North Star.md, Green.md,
and docs/. Licensed under MIT.
Available Tools
6 toolscompare_energyA
Measure two commands and report which consumes less energy and by what margin.
Only meaningful if both commands are functionally equivalent (same outputs for the same inputs) — verify that separately before drawing conclusions.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| repeats | No | ||
| command_a | Yes | ||
| command_b | Yes | ||
| idle_seconds | No |
TDQS
A3.7/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states the tool measures energy and reports margin, implying a read-only operation, but does not explicitly disclose non-destructiveness or any behavioral traits like permissions. Adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise, front-loaded sentences with no waste. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 parameters, no output schema, and no annotations, the description is insufficient. It omits return format, parameter details, and how the measurement works, leaving the agent underinformed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must explain parameters. It fails to describe 'repeats', 'idle_seconds', or the meaning of command_a and command_b beyond their names. No parameter semantics are provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool measures two commands to compare energy consumption and reports the margin. The verb 'measure' and resource 'energy' are specific, and the purpose is distinct from siblings like verify_equivalence and compare_tokens.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states the tool is only meaningful if commands are functionally equivalent and advises to verify equivalence separately, pointing to the sibling tool verify_equivalence. This provides clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
compare_tokensA
Measure two programs' token use and report which uses fewer, by how much. Only meaningful if both produce acceptable equivalent results — verify that separately (fewer tokens with worse answers is not a win).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| upstream | No | https://api.anthropic.com | |
| command_a | Yes | ||
| command_b | Yes | ||
| base_url_env | No | ANTHROPIC_BASE_URL |
TDQS
A4.1/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full behavioral transparency burden. It clearly describes what the tool does (compares token usage) but does not detail how tokens are counted or if there are any side effects. The behavior is straightforward and non-destructive, so transparency is high.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two sentences, each essential. The first states the core function; the second adds critical context. No superfluous content. Perfectly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (4 params, no output schema). The description explains the main output (which program uses fewer tokens and by how much) but lacks specifics on the exact format (e.g., token counts, percentage). Close to complete but leaves a minor gap for output details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description provides no explanation of the parameters (command_a, command_b, upstream, base_url_env). It fails to clarify how programs are specified or the role of optional parameters, leaving the agent without necessary semantic guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's verb (measure/compare) and resource (token use of two programs). It distinguishes it from siblings like 'compare_energy' and 'verify_equivalence' by focusing on token comparison.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use the tool (to compare token usage) and provides a critical precondition: programs must produce equivalent results. It warns against using it when results are not equivalent and hints at using 'verify_equivalence' separately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
energy_backend_infoA
Report whether energy measurement is available on this host and which backend would be used. Call this before measure_energy to know if the energy axis works here — on a machine with no reachable CPU power sensor it returns energy_available: false, and you should rely on the token axis (or say energy can't be measured) rather than estimate.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
A4.8/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full behavioral disclosure. It explains the condition for returning energy_available: false and the recommended alternative action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description covers the main return value (energy_available) and usage context, but could slightly benefit from more precise return format details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist and schema coverage is 100%. With 0 parameters, the baseline is 4, and no additional semantics are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it reports energy measurement availability and backend, and distinguishes from sibling tools like measure_energy by advising to call this first.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Call this before measure_energy' and provides clear guidance on what to do if energy is not available (rely on token axis or state can't measure).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
measure_energyA
Measure the electrical energy (joules) a shell command consumes while running.
Methodology: samples CPU package power at 100 ms during the run, subtracts a separately measured idle baseline, repeats the run (default 3x) and reports mean/stdev/CV. Use absolute paths; wrap any path containing spaces in double quotes. Expect ~(idle_seconds + repeats x runtime) of wall time.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| command | Yes | ||
| repeats | No | ||
| idle_seconds | No |
TDQS
A4.4/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description fully discloses the methodology: sampling CPU power at 100ms, subtracting idle baseline, repeating runs (default 3x), and reporting mean/stdev/CV. It also notes expected wall time, providing clear behavioral insight.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a clear first sentence, method details, usage notes, and a time estimate. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and lack of output schema, the description covers measurement methodology, parameters, output statistics, and wall time. It is largely complete, though the return format of the statistics is not explicitly described.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates well by explaining the purpose of 'repeats' (default 3x) and 'idle_seconds' (idle baseline). It also advises on handling paths, adding meaning beyond the schema. However, it does not detail all parameters' formats or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: measuring electrical energy consumed by a shell command. It uses a specific verb ('measure') and resource ('electrical energy in joules'), and distinguishes from siblings like 'compare_energy' by focusing on a single command.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for measuring energy of a shell command but does not explicitly state when to use this tool versus alternatives like 'compare_energy' or 'energy_backend_info'. No exclusions or when-not-to-use guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
measure_tokensA
Measure how many LLM tokens a program consumes when it runs (works on any machine — no
special hardware). The program must read base_url_env for its LLM endpoint (most SDKs do);
we point that at a non-blocking counting proxy forwarding to upstream, run the program, and
report real provider usage (input/output/total tokens, call count). For a non-Anthropic
target, pass its provider's base-url env var and upstream (e.g. OPENAI_BASE_URL,
https://api.openai.com). If llm_calls is 0, the target didn't route through base_url_env.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| command | Yes | ||
| upstream | No | https://api.anthropic.com | |
| base_url_env | No | ANTHROPIC_BASE_URL |
TDQS
A4.5/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully reveals internal behavior: it sets up a non-blocking counting proxy, runs the program, and reports usage. It also explains the consequence of zero llm_calls and the env var dependency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph of about 100 words, efficiently covering purpose, mechanism, usage tips, and edge cases without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description explains what will be reported (input/output/total tokens, call count) and addresses the zero-call scenario. It covers all necessary aspects for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description adds meaning to 'base_url_env' and 'upstream' by explaining their roles in the proxy mechanism. 'command' is implied but not detailed. Partially compensates for low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific verb 'measure' and the resource 'LLM tokens consumed by a program'. It differentiates from sibling tools like measure_energy by focusing on tokens and mentions the proxy-based method.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides context on when to use: for measuring token consumption of programs that read an LLM endpoint from an environment variable. Gives guidance for different providers and explains the zero-call edge case. However, does not explicitly state when not to use or list alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
verify_equivalenceA
Run two commands and compare stdout + exit code. The gate before any energy/token comparison.
With no stdin_inputs it's a single-input smoke test. Pass stdin_inputs (a list of strings fed to each program's stdin) to run an input BATTERY — all inputs must match. Stronger evidence still comes from running the project's own test suite.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| command_a | Yes | ||
| command_b | Yes | ||
| stdin_inputs | No |
TDQS
A4.6/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full burden. It explains the comparison logic and input modes. However, it does not disclose that the commands may have arbitrary side effects (destructiveness), which is a notable gap for a tool that executes arbitrary commands.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four concise, well-structured sentences. Purpose is front-loaded, usage variations are logically separated, and no unnecessary text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, usage, and parameter semantics well. However, it does not describe the return value (e.g., boolean, diff output) despite having no output schema. This is a minor but relevant omission.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. It effectively explains the stdin_inputs parameter and its behavior (list of strings fed to stdin, requiring all outputs to match). The command_a and command_b parameters are only implied, but the tool's purpose is clear enough.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it runs two commands and compares stdout and exit code. It also distinguishes itself as a gate before energy/token comparisons relative to siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly positions itself as a preliminary gate before energy/token comparisons. Describes two usage modes (single-input smoke test vs. input battery) and recommends the project's own test suite for stronger evidence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
6 tool updates
v0.1.0- First observed
compare_energy - First observed
compare_tokens - First observed
energy_backend_info - First observed
measure_energy - First observed
measure_tokens - First observed
verify_equivalence
TDQS
A4.3/5.0
Disambiguation5/5
Each tool has a clearly distinct purpose: measuring vs comparing energy vs tokens, verifying equivalence, and checking backend availability. No two tools overlap in function.
Naming Consistency4/5
Most tools follow a consistent verb_noun pattern (compare_energy, compare_tokens, measure_energy, measure_tokens, verify_equivalence). However, energy_backend_info breaks the pattern with a noun_noun structure, causing a minor inconsistency.
Tool Count5/5
With 6 tools, the server is well-scoped. It covers all core operations (measure, compare, verify, and check backend) without being overly numerous or too sparse.
Completeness5/5
The tool set is complete for its domain: it provides the necessary steps to measure energy/tokens, compare two commands, verify equivalence, and check measurement availability. No obvious gaps.
Maintenance
ActivityMaintained
ResponsivenessNo issues
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
Exact Claude API cost calc with real cache economics, plus a tiktoken-misuse scanner.
Agent Cost Allocator MCP — multi-tenant LLM cost attribution for chargeback billing. Companion to
See, price, and control every tool call your AI agents make: policy checks, cost, and audit tools.
Enterprise AI Control Plane: governance, guardrails, spend tracking, compliance & smart routing.
Related MCP Servers
- AlicenseAqualityDmaintenanceTracks AI agent token usage and spending in real time, with budget alerts, per-task cost breakdown, and a visual dashboard.61MIT
- FlicenseNot gradedqualityBmaintenanceLocal LLM cost & token forensics proxy with anomaly detection, enabling security teams to scan for cost anomalies and abuse patterns, and expose results via MCP for autonomous agents.-
- FlicenseAqualityBmaintenanceEstimates the environmental footprint of your AI use — energy (kWh), miles driven, water used for cooling, and CO₂ — plus a prompt-efficiency score, working with any AI client by measuring token usage.9-
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/rlawogh1005/green-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server