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: 计算差旅费用的排放

资源

• 碳计算结果作为具有 climatiq://calculation/{id} URI 方案的资源暴露
• 每个资源包含有关排放因子和计算结果的详细信息

提示

• 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 工具：使用 set-api-key 工具在运行时通过 AI 助手配置

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

   CLIMATIQ_API_KEY=your_climatiq_api_key
   

获取 Climatiq API 密钥的方法：

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

运行服务器

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

climatiq-mcp-server

在 AI 助手中设置

Claude 桌面版

在 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 笔记本
• simple_test.py: 一个简单的工具，用于直接测试 API 集成，无需 MCP 协议

# Run the simple test
python examples/simple_test.py

实用脚本

utils/ 目录中包含几个有用的脚本：

测试客户端

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

python utils/test_client.py

LLM 示例客户端

llm_example_client.py 脚本展示了大型语言模型（如 Claude）如何与 Climatiq MCP 服务器交互：

python utils/llm_example_client.py

主要特性：

• 完整的 API 封装，包括错误处理和超时管理
• 资源和结果缓存，以保存计算历史
• 示例提示，展示如何生成自然语言解释
• 展示了电力排放、旅行排放和排放因子搜索功能

命令行工具

一个命令行接口工具，可直接访问 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

关键概念

活动 ID

活动 ID 是 Climatiq API 中的一个关键概念，它将类似的排放因子分组：

• Climatiq 数据库中的每个排放因子都有一个活动 ID
• 活动 ID 将描述相同活动但在不同地区、年份、来源等的排放因子分组
• 示例：electricity-supply_grid-source_residual_mix（电力），passenger_vehicle-vehicle_type_car（汽车旅行）

计算方法

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

1. 基于距离的方法 用于旅行排放
2. 高级旅行计算 使用起始-目的地对
3. 基于支出的方法 当您只有支出数据时
4. 直接计算 使用特定的排放因子

故障排除

API 密钥问题

1. 确保 CLIMATIQ_API_KEY 在您的环境或 .env 文件中正确设置
2. 在 Climatiq 仪表板中验证 API 密钥是否有效
3. 使用 examples/simple_test.py 检查您的 API 密钥是否工作正常

高级用法

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

关于 Climatiq

Climatiq 提供了一个强大的碳智能 API，允许您计算来自电力使用、交通、采购等方面的排放。这个 MCP 服务器通过模型上下文协议使这些功能可以被 AI 助手访问。

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

许可证

此项目采用 MIT 许可证进行授权 - 详情请参见 LICENSE 文件。