AQICN MCP Server

AQICN MCP 服务

这是一个 Model Context Protocol（MCP）服务，提供来自 World Air Quality Index（AQICN）项目的空气质量数据工具。它允许大模型获取全球各城市和坐标位置的实时空气质量数据。

安装

通过 Smithery 安装

通过 Smithery 自动为 Claude Desktop 安装 AQICN MCP 服务：

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

使用推荐的 uv 手动安装

我们建议使用 uv 管理 Python 环境：

# Install the package and dependencies
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 Inspector 测试和调试服务是最快捷的方式：

mcp dev aqicn_server.py

集成 Claude Desktop

服务准备就绪后，在 Claude Desktop 中安装：

mcp install aqicn_server.py

直接执行

用于测试或自定义部署：

python aqicn_server.py

可用工具

1. city_aqi

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

@mcp.tool()
def city_aqi(city: str) -> AQIData:
    """Get air quality data for a specific city."""

输入：

• city：要获取空气质量数据的城市名称

**输出：**包含以下内容的 AQIData：

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

2. geo_aqi

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

@mcp.tool()
def geo_aqi(latitude: float, longitude: float) -> AQIData:
    """Get air quality data for a specific location using coordinates."""

输入：

• latitude：位置的纬度
• longitude：位置的经度

**输出：**与 city_aqi 相同

3. search_station

按关键词搜索空气质量监测站。

@mcp.tool()
def search_station(keyword: str) -> list[StationInfo]:
    """Search for air quality monitoring stations by keyword."""

输入：

• keyword：用于搜索站点的关键词（城市名称、站点名称等）

**输出：**包含以下内容的 StationInfo 列表：

• name：站点名称
• station_id：站点唯一标识符
• coordinates：站点的纬度和经度

使用示例

使用 MCP Python 客户端：

from mcp import Client

async with Client() as client:
    # Get air quality data for Beijing
    beijing_data = await client.city_aqi(city="beijing")
    print(f"Beijing AQI: {beijing_data.aqi}")

    # Get air quality data by coordinates (Tokyo)
    geo_data = await client.geo_aqi(latitude=35.6762, longitude=139.6503)
    print(f"Tokyo AQI: {geo_data.aqi}")

    # Search for stations
    stations = await client.search_station(keyword="london")
    for station in stations:
        print(f"Station: {station.name} ({station.coordinates})")

贡献

欢迎提交问题和拉取请求。请确保你的更改包含适当的测试和文档。

许可证

本项目采用 MIT License 许可。