Climatiq MCP Server

Climatiq MCP 服务

一个用于访问 Climatiq API 并计算碳排放量的 Model Context Protocol（MCP）服务。借助此服务，AI 助手能够实时计算碳排放量，并提供气候影响洞察。

演示

https://github.com/user-attachments/assets/c253d6d1-ccf6-4c14-965e-6023ba2a0296

https://github.com/user-attachments/assets/d61c1181-acf6-4d9f-9a48-537fc64ac4c3

功能

此 MCP 服务集成了 Climatiq API，可为 AI 助手提供碳排放计算功能：

工具

• 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：计算差旅费用产生的碳排放量

资源

• 碳排放计算结果以资源形式提供，URI 方案为 climatiq://calculation/{id}
• 每个资源都包含排放因子和计算结果的详细信息

提示词

• climate-impact-explanation：以自然语言说明特定排放计算对气候的影响

安装

从源代码安装

此项目使用 uv 管理虚拟环境和依赖项。请先安装 uv。

# Clone the repository
git clone https://github.com/your-org/climatiq-mcp-server.git
cd climatiq-mcp-server

# Create a virtual environment
uv venv

# Activate the virtual environment
# On macOS/Linux:
source .venv/bin/activate
# On Windows:
.venv\Scripts\activate

# Install dependencies with development extras
uv sync --dev --extra all

使用 uv

uv pip install climatiq-mcp-server

API 密钥配置

此服务需要 Climatiq API 密钥才能运行。你可以通过以下几种方式提供密钥：

1. 环境变量：启动服务前设置 CLIMATIQ_API_KEY 环境变量

   export CLIMATIQ_API_KEY=your_climatiq_api_key
   

2. 安装期间配置：

   CLIMATIQ_API_KEY=your_climatiq_api_key uv pip install climatiq-mcp-server
   

3. set-api-key 工具：在运行期间，通过 AI 助手使用 set-api-key 工具进行配置

4. 配置文件：在项目目录中创建 .env 文件：

   CLIMATIQ_API_KEY=your_climatiq_api_key
   

获取 Climatiq API 密钥：

1. 在 app.climatiq.io 注册
2. 按照获取 API 密钥中的说明操作

运行服务

可以直接从命令行启动服务：

climatiq-mcp-server

在 AI 助手中设置

Claude Desktop

MacOS：~/Library/Application\ Support/Claude/claude_desktop_config.json Windows：%APPDATA%/Claude/claude_desktop_config.json

"mcpServers": {
  "climatiq-mcp-server": {
    "command": "climatiq-mcp-server",
    "env": {
      "CLIMATIQ_API_KEY": "your_climatiq_api_key"
    }
  }
}

示例和实用工具

示例目录

examples/ 目录包含：

• climatiq.ipynb：演示如何直接使用 Climatiq API 的 Jupyter notebook
• simple_test.py：用于直接测试 API 集成（不使用 MCP 协议）的简单实用工具

# Run the simple test
python examples/simple_test.py

实用脚本

utils/ 目录包含多个实用脚本：

测试客户端

test_client.py 脚本会测试所有工具、提示词和资源：

python utils/test_client.py

大模型示例客户端

llm_example_client.py 脚本演示大模型（例如 Claude）如何与 Climatiq MCP 服务交互：

python utils/llm_example_client.py

主要功能：

• 完整的 API 封装，支持错误处理和超时管理
• 缓存资源和结果，保留计算历史记录
• 提供示例提示词，展示如何生成自然语言说明
• 演示电力排放、出行排放和排放因子搜索功能

CLI 工具

一种命令行界面工具，可直接访问 API，无需处理 MCP 服务的复杂性：

# For electricity emissions
python utils/climatiq_cli.py electricity --energy 1000 --unit kWh --region US

# For travel emissions
python utils/climatiq_cli.py travel --mode car --distance 100 --unit km --region US

运行 MCP 服务脚本

使用 run_mcp_server.py 脚本，无需安装即可直接运行服务：

python utils/run_mcp_server.py

核心概念

Activity ID

Activity ID 是 Climatiq API 中的一个关键概念，用于将相似的排放因子归为一组：

• Climatiq 数据库中的每个排放因子都有一个 Activity ID
• Activity ID 会将描述同一活动的排放因子归为一组，这些因子可能来自不同地区、年份、来源等
• 示例：electricity-supply_grid-source_residual_mix（电力）、passenger_vehicle-vehicle_type_car（汽车出行）

计算方法

Climatiq MCP 服务支持多种计算方法：

1. 基于距离的方法，用于计算出行排放
2. 高级出行计算，使用起点—终点组合
3. 基于支出的方法，适用于只有支出数据的情况
4. 直接计算，使用特定排放因子

故障排除

API 密钥问题

1. 确保已在环境或 .env 文件中正确设置 CLIMATIQ_API_KEY
2. 在 Climatiq 控制面板中确认 API 密钥处于有效状态
3. 使用 examples/simple_test.py 检查 API 密钥是否正常工作

高级用法

有关特定工具和高级功能的详细文档，请参阅 docs/README.md 文件。

关于 Climatiq

Climatiq 提供强大的碳排放智能 API，可用于计算电力使用、交通运输、采购等方面的排放量。此 MCP 服务通过模型上下文协议，让 AI 助手能够使用这些功能。

如需了解关于 Climatiq 的更多信息，请访问 climatiq.io。

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。