Climatiq MCP Server 是一个 Model Context Protocol（MCP）服务器，用于访问 Climatiq API 以计算碳排放，使 AI 助手能够执行实时碳计算并提供气候影响洞察。
用途
该服务器将 Climatiq API 的碳计算能力通过 MCP 协议暴露给 AI 助手，使其能够在对话或任务中直接调用碳排放计算功能。
主要能力
该 MCP 服务器集成 Climatiq API，提供以下工具：
- set-api-key：配置用于认证的 Climatiq API 密钥。
- electricity-emission：计算电力消耗产生的碳排放。
- travel-emission：计算汽车、飞机或火车出行的碳排放。
- search-emission-factors：在 Climatiq 数据库中搜索特定的排放因子。
- custom-emission-calculation：使用特定排放因子执行自定义计算。
- cloud-computing-emission：计算云计算资源使用产生的排放。
- freight-emission：计算货运运输产生的排放。
- procurement-emission：计算采购支出产生的排放。
- hotel-emission：计算酒店住宿产生的排放。
- travel-spend：计算差旅费用产生的排放。
- climate-impact-explanation：针对特定排放计算生成自然语言解释。
碳计算结果以资源形式暴露，URI 方案为 climatiq://calculation/{id}，每个资源包含排放因子和计算结果的详细信息。
使用方式
项目使用 uv 进行虚拟环境和依赖管理，需先安装 uv。
API 密钥配置有几种方式：
- 环境变量：在启动服务器前设置 CLIMATIQ_API_KEY 环境变量，例如
export CLIMATIQ_API_KEY=your_climatiq_api_key。 - 安装时配置：
CLIMATIQ_API_KEY=your_climatiq_api_key uv pip install climatiq-mcp-server。 - 运行时使用 set-api-key 工具在 AI 助手中配置。
- 配置文件：在项目目录创建 .env 文件，内容为
CLIMATIQ_API_KEY=your_climatiq_api_key。
获取 Climatiq API 密钥：在 app.climatiq.io 注册，并按照 Getting API Keys 的说明操作。
服务器可直接从命令行启动。在 AI 助手中设置：macOS 路径为 ~/Library/Application Support/Claude/claude_desktop_config.json，Windows 路径为 %APPDATA%/Claude/claude_desktop_config.json。
examples/ 目录包含：climatiq.ipynb（演示直接使用 Climatiq API 的 Jupyter notebook）、simple_test.py（不通过 MCP 协议直接测试 API 集成的简单工具）。
utils/ 目录包含多个实用脚本：test_client.py 测试所有工具、提示和资源；llm_example_client.py 演示大型语言模型（如 Claude）如何与 Climatiq MCP 服务器交互；还包含带错误处理和超时管理的完整 API 包装器、用于保留计算历史的资源和结果缓存、生成自然语言解释的示例提示、电力排放和差旅排放及排放因子搜索能力的演示，以及无需 MCP 服务器复杂性的直接 API 访问命令行界面工具。可使用 run_mcp_server.py 脚本直接运行服务器而无需安装。
适用场景
适用于需要让 AI 助手进行碳排放计算、查询排放因子、生成气候影响自然语言解释的场景，覆盖电力、差旅、货运、采购、云计算、酒店住宿等排放类别。
限制
必须拥有有效的 Climatiq API 密钥，且需要正确配置。项目使用 uv 管理依赖。若 API 密钥无效或未设置，功能无法使用，可参考故障排除：确保 CLIMATIQ_API_KEY 在环境或 .env 文件中正确设置；在 Climatiq 仪表板验证 API 密钥是否激活；使用 examples/simple_test.py 检查 API 密钥是否正常工作。更详细的文档见 docs/README.md。项目采用 MIT 许可证。
