aqicn-mcp

🚀 AQICN MCP 服务器

这是一个模型上下文协议（MCP）服务器，提供来自世界空气质量指数（AQICN）项目的城市空气质量管理工具。它允许大型语言模型（LLMs）实时获取全球城市和坐标位置的空气质量数据。

🚀 快速开始

本服务器允许大型语言模型实时获取全球城市和坐标位置的空气质量数据，下面为你介绍其安装、配置、运行等相关信息。

📦 安装指南

通过 Smithery 安装

要自动安装 AQICN MCP 服务器以供 Claude Desktop 使用，请访问 Smithery：

npx -y @smithery/cli install @mattmarcin/aqicn-mcp --client claude

推荐使用 uv 手动安装

我们推荐使用 uv 来管理 Python 环境：

# 安装包及依赖项
uv pip install -e .

🔧 环境配置

在项目根目录中创建一个 .env 文件（可以复制自 .env.example）：

# .env
AQICN_API_KEY=your_api_key_here

或者直接设置环境变量：

# Linux/macOS
export AQICN_API_KEY=your_api_key_here

# Windows
set AQICN_API_KEY=your_api_key_here

🚀 运行服务器

开发模式

使用 MCP 检查工具快速测试和调试：

mcp dev aqicn_server.py

集成到 Claude Desktop

准备就绪后，安装到 Claude Desktop：

mcp install aqicn_server.py

直接运行

用于测试或自定义部署：

python aqicn_server.py

💻 使用示例

基础用法

# 查询北京市空气质量
result = city_aqi("北京")

# 根据坐标查询某地的空气质量
result = geo_aqi(39.9042, 116.5591)

# 搜索所有空气质量监测站
stations = search_station("北京")

✨ 主要特性

1. city_aqi

获取特定城市的空气质量数据。

@mcp.tool()
def city_aqi(city: str) -> AQIData:
    """获取特定城市的空气质量数据。"""

输入：

• city：要查询的 cityName

输出：包含以下信息的 AQIData：

• aqi：空气质量指数值
• station：监测站名称
• dominant_pollutant：主要污染物（如有）
• time：测量时间戳
• coordinates：监测站经纬度

2. geo_aqi

根据坐标获取特定位置的空气质量数据。

@mcp.tool()
def geo_aqi(latitude: float, longitude: float) -> AQIData:
    """根据坐标获取特定位置的空气质量数据。"""

输入：

• latitude：纬度值
• longitude：经度值

输出：与 city_aqi 相同

3. search_station

通过关键字搜索空气质量监测站。

@mcp.tool()
def search_station(keyword: str) -> list[StationInfo]:
    """根据关键字搜索空气质量监测站。"""

输入：

• keyword：搜索关键字（城市名称、站点名称等）

输出：包含以下信息的 StationInfo 列表：

• name：站点名称
• station_id：唯一的站点 ID
• coordinates：站点经纬度

⚠️ 注意事项

⚠️ 重要提示

安装前请确保已获取 AQICN 平台的有效 API Key。

💡 使用建议

如有任何问题，请访问 GitHub 查看文档或提交 issue。

感谢使用 AQICN MCP 服务器！