Lead Green

leadgreen-mcp

Lead Green 是一个公开索引，按模型、GPU 和配置列出运行一百万个输出 token 所需的 GPU 能耗（每百万个输出 token 的瓦时），并提供电网碳强度数据，以便计算任意地点的能耗成本。该索引以开放数据形式发布，提供 JSON API 和 MCP 服务，采用 CC BY 4.0 许可。每项数据都注明了公开来源和检索日期；这是 Katonic 的项目，由 Katonic 运营并出资，不接受硬件、云或模型供应商的资金。

Lead Green 由 Katonic 运营并出资。Katonic 销售主权 AI 平台，不接受硬件、云或模型供应商的资金。

此软件包是该索引的 MCP 服务：按模型、GPU 和配置列出每百万个输出 token 的 GPU 瓦时，并提供按国家划分的电网碳强度数据及 GPU 硬件参考数据。每个回答都会标明来源，并附带说明：这些数据仅统计 GPU 能耗，是在繁忙服务器上测得的下限。

安装

pip install leadgreen-mcp

或者无需安装，使用 uvx leadgreen-mcp。

同一个 wheel 也可从网站下载，其 SHA-256 值见 https://leadgreen.ai/mcp/：

pip install https://leadgreen.ai/dist/leadgreen_mcp-0.3.1-py3-none-any.whl

源代码也可通过 pip install "git+https://github.com/katonic-dev/leadgreen-ai#subdirectory=leadgreen-mcp" 安装。

需要 Python 3.10 或更高版本。兼容 mcp Python SDK 1.x 和 2.x。已列入官方 MCP Registry，名称为 ai.leadgreen/green-token-index。

版本

软件包和数据分别采用独立的版本号。软件包版本为 0.3.1（见此文件、pyproject.toml 和 wheel 文件名）。数据的版本是 Lead Green API 的一个带日期的发布版本；软件包内置的数据副本对应 leadgreen_mcp/data/manifest.json 中标明的版本（data_version）。服务会优先读取实时 API，因此无论安装的是哪个软件包版本，会话通常都会使用当前版本的数据作答。每个响应都会通过 data_source 和 data_updated 指明所用版本。

工具

工具	回答内容
list_models	索引中包含哪些模型，以及它们对应哪些 GPU
energy_per_million_tokens(model, gpu?, itl_deadline_ms?)	某个模型在每种 GPU 上能耗最低的数据行
estimate(model, output_tokens, gpu?, country?, running_batch?, num_gpus?, itl_deadline_ms?, pue?, system_power_ratio?)	指定 token 数量的 GPU 能耗（Wh 和 kWh）、对应电网的 kg CO2e，以及可选的电表能耗
compare_gpus(model, itl_deadline_ms?)	比较某个模型在 H100 与 B200 上的表现
concurrency_curve(model, gpu)	每种已测运行批次下的每 token 能耗
grid_intensity(country)	某个国家或 World 的年度平均 gCO2e/kWh
gpu_hardware(gpu?)	最大 TDP、内存、MIG 配置和整机能耗上限
sources	所有来源、版本、检索日期和许可

资源：leadgreen://manifest。

参数

• running_batch：服务器持有的平均运行批次，即同时解码的请求数（vLLM num_requests_running）。随后，估算会使用与该值最接近的已测配置，且 GPU 数量与最佳行相同（例如，Qwen 3 32B 使用 2 x H100）；只有当该 GPU 数量没有测量数据时，才会扩展到所有 GPU 数量。requests_in_flight 是旧名称，仍可使用；若同时提供这两个参数且值不同，则会报错。响应会同时包含 avg_running_batch 和 avg_requests_in_flight（数值相同）。
• num_gpus：仅使用 GPU 数量恰好为此值的配置。
• itl_deadline_ms：选择最佳行时的延迟上限。会保留中位数令牌间延迟不超过此值的行，并选择能耗最低的一行。默认值为 500 ms，与排行榜自身的默认值相同。
• pue 和 system_power_ratio（均须至少为 1.0）：提供其中任一参数时，estimate 还会返回电表端能耗，即 GPU 能耗 x system_power_ratio x pue，并注明这是电表端能耗，与 GPU 数值并列显示。这些是你的假设，并非测量值。作为参考，DGX B200 的最大功率为 14.3 kW，GPU 功率为 8 x 1.0 kW，两者之比约为 1.79。
• country：国家/地区名称、该网站使用的简称、ISO 3166 alpha-3 或 alpha-2 代码，或 World。常见名称均可使用：UK、GB、Britain、US、USA、America、Turkey、Korea、South Korea、Russia。精确匹配优先于部分匹配；查询长度不超过三个字符时必须精确匹配，因此 US 不会匹配到 Australia。电网数据为 2024 年年度平均值；years 和 latest_year 会显示其他可用年份。这些是生命周期、基于地点的数据，用于比较不同地点，并非用于申报的 Scope 2 数据。

每个响应中的字段

• caveat：每个工具返回的都是同一句说明，取自 API 的 index.json。请原样传递。
• boundary：测量数据的值为 gpu_only。
• data_source：live（从 API 获取）、bundled snapshot（软件包中附带的副本）或 local folder（当 LEADGREEN_API_BASE 为文件夹时）。
• data_updated 和 data_version：数据的时效性信息。

服务发送的内容及发送位置

• 仅向 https://leadgreen.ai/api/v1（或你设置的基础地址）发送 HTTP GET 请求，以获取已发布的 JSON 文件：每个会话中每个文件最多获取一次，之后会缓存在内存中。
• 你的问题、提示词和工具参数绝不会离开你的机器。请求中不会携带这些内容；查询和运算都在本地进行。
• 如果获取失败，服务会向 stderr 打印一行信息，并在本次会话剩余时间内使用附带的快照，不再尝试连接网络。
• 如需完全离线使用，请将 LEADGREEN_API_BASE 设置为包含 API 文件的本地文件夹（例如 leadgreen_mcp/data 的副本）。其他 URL 也可使用。

客户端配置

Claude Desktop 或 Cursor（claude_desktop_config.json / .cursor/mcp.json）：

{ "mcpServers": { "leadgreen": { "command": "leadgreen-mcp" } } }

离线使用：

{ "mcpServers": { "leadgreen": { "command": "leadgreen-mcp", "env": { "LEADGREEN_API_BASE": "/path/to/api/v1" } } } }

Claude Code：claude mcp add leadgreen -- leadgreen-mcp

如果 Claude Desktop 找不到 leadgreen-mcp

从 Finder、Dock 或 Start 菜单启动的 Claude Desktop 无法读取终端使用的 PATH，因此单独使用 leadgreen-mcp 可能无法启动。请改用完整路径：运行 which leadgreen-mcp（macOS、Linux）或 where leadgreen-mcp（Windows），并将结果填入 command。也可以将 command 指向 Python 的完整路径，并设置 "args": ["-m", "leadgreen_mcp.server"]。

许可证

代码采用 Apache 2.0 许可证（参见 LICENSE）。数据沿用其来源所采用的许可证，详见清单。