green-mcp

Green Agent

プログラムの効率を測る 2 つの軸に対応し、動作を維持したままコストを削減する、プラグイン可能な MCP サーバーです。

• CPU エネルギー — AMD uProf／Linux RAPL／macOS powermetrics による実機のテレメトリーから、コードが実際に消費したジュール数を測定します。ホストに応じて自動的に選択されます。
• LLM トークン — LLM を呼び出すプログラムのトークン使用量（入力／出力／キャッシュ／推論）を、プロバイダーに依存せず、非ブロッキングで測定します。

基本方針：推定ではなく、必ず測定します。 すべての主張には、コマンド、数値、実行ごとの不確実性を伴う測定結果が必要です。そうでない場合は推定値と明記します。比較判定にはヒューリスティックではなく、アイドル時のベースラインの不確実性を織り込んだ、Welch の t 検定を用います。

クイックスタート

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

IDE にマウントします（設定は deploy/ にあります）。

IDE	ファイル
Claude Code	.mcp.json
Cursor	.cursor/mcp.json
OpenAI Codex	~/.codex/config.toml（codex mcp add green -- green-mcp）
Google Antigravity	~/.gemini/mcp_config.json

エージェントに、コマンドのエネルギー／トークンを測定または比較するよう依頼してください。マウントとハーネスの詳しいガイドは deploy/README.md を参照してください。

ツール

measure_energy · compare_energy · measure_tokens · compare_tokens · verify_equivalence · energy_backend_info

要件（各機能を実際に動作させるために必要なもの）

ホストするサーバーは不要です。 green-mcp はウェブサービスではなく、IDE がローカルの stdio サブプロセスとして起動します。クラウドもアカウントも不要で、測定サーバー自体に LLM キーも必要ありません。

サーバーを実行するには	Python 3.10 以降、pip install green-mcp。以上です。ツールはすぐにマウントできます。

エネルギー軸 — ホスト上に電力センサーのバックエンドが必要です（最も大きな前提条件です）。

• Windows + AMD → AMD uProf を別途インストールします（ドライバー方式のため、インストールには管理者権限が必要です）。同梱されていません。
• Linux → /sys/class/powercap（RAPL）を読み取ります。追加のインストールは不要ですが、一部のディストリビューションでは energy_uj の読み取りに root 権限が必要です。
• macOS → 組み込みの powermetrics を使用します。root 権限／パスワードなしの sudo が必要です。
• 利用可能なセンサーがない場合（VM、コンテナー、制限されたマシンなど）→ エネルギーツールは energy_available: false を報告し、推定を行いません。エネルギー測定は一般に Docker／CI では動作しません — コンテナーや VM には電力センサーのパススルーがないためです。その場合はトークン軸を使用してください。
• 測定対象のコマンドはローカルで実行されます（任意のコマンドを実行するため、信頼できる環境でのみ使用してください）。

トークン軸 — 特別なハードウェアは不要で、どこでも動作します。**ただし、**次の条件があります。

• 測定対象のプログラムが LLM エンドポイントを 環境変数（ANTHROPIC_BASE_URL、OPENAI_BASE_URL など）から読み込む必要があります。そうすることで、カウント用プロキシを経由させられます。エンドポイントがハードコードされている場合は測定されず、呼び出し数は 0 と報告されます。
• 測定では対象プログラムの実際の LLM 呼び出しを実行します。プロキシは実際のプロバイダーにリクエストを転送するため、対象プログラムの API キーには通常どおり料金が発生し、プロバイダーへのネットワークアクセスも必要です。

同梱のエージェント（任意） — pip install green-mcp[agent] を実行すると Claude Agent SDK が追加され、Anthropic の認証情報が必要になります。MCP サーバー単体では不要です。

適用範囲について

• エネルギーはCPU パッケージのエネルギー（RAPL では DRAM も含む）です。炭素排出量でも、システム全体のエネルギーでもありません。
• 異なるバックエンドの数値は比較できません。
• 実機での再現性が検証されているのは AMD/uProf バックエンドのみです。Linux／macOS の実装は記述され、ユニットテストも実施されていますが、実機では未検証です。また、壁コンセント電力計との相互検証が済んでいるバックエンドはありません。一方、トークン測定器は実際のプロバイダーで検証済みです（NVIDIA NIM、OpenAI 互換：ストリーミングと非ストリーミングで実際に 5 回呼び出し、プロバイダー自身の使用記録と完全に一致）。ただし、Anthropic 形式の usage 経路とレート制限の動作は、ローカルの偽アップストリームに対するテストのみです。これらの未解決事項は隠さず、追跡しています。

開発

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)

アーキテクチャと設計上の決定は、North Star.md、Green.md、 および docs/ に記載されています。MIT ライセンスの下で提供されています。