MCP 服务器

Climatiq MCP Server

一个模型上下文协议服务器，它通过与 Climatiq API 交互，使 AI 助手能够执行实时碳排放计算并提供气候影响洞察。

README

Climatiq MCP 服务器

一个用于访问 Climatiq API 以计算碳排放的模型上下文协议 (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。

# 克隆仓库
git clone https://github.com/your-org/climatiq-mcp-server.git
cd climatiq-mcp-server

# 创建一个虚拟环境
uv venv

# 激活虚拟环境
# 在 macOS/Linux 上:
source .venv/bin/activate
# 在 Windows 上:
.venv\Scripts\activate

# 安装带有开发扩展的依赖项
uv sync --dev --extra all

使用 uv

uv pip install climatiq-mcp-server

API 密钥配置

服务器需要 Climatiq 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 助手中使用 set-api-key 工具在运行时配置它
配置文件: 在项目目录中创建一个 .env 文件：
```
CLIMATIQ_API_KEY=your_climatiq_api_key
```

要获取 Climatiq API 密钥：

在 app.climatiq.io 注册
按照获取 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"
    }
  }
}

</details>

示例和实用程序

示例目录

examples/ 目录包含：

climatiq.ipynb: 一个 Jupyter notebook，演示了使用 Climatiq 的直接 API 用法
simple_test.py: 一个简单的实用程序，用于直接测试 API 集成，无需 MCP 协议

# 运行简单测试
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 包装器，具有错误处理和超时管理
资源和结果缓存，以保留计算历史记录
示例提示，展示如何生成自然语言解释
演示了电力排放、旅行排放和排放因子搜索功能

CLI 工具

一个命令行界面工具，用于直接 API 访问，无需 MCP 服务器的复杂性：

# 对于电力排放
python utils/climatiq_cli.py electricity --energy 1000 --unit kWh --region US

# 对于旅行排放
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（汽车旅行）