# AQICN MCP Server

[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-Compatible-orange.svg)](https://modelcontextprotocol.io/)

一个用于查询中国城市空气质量信息的 MCP 服务器，直接查询实时空气质量数据。

## 功能特性

- 根据城市拼音查询实时空气质量指数 (AQI)
- 返回完整的空气质量数据，包括 PM2.5、PM10、二氧化硫、二氧化氮等污染物信息
- 支持中国所有主要城市查询
- 提供空气质量等级描述和健康建议

## 安装步骤

### 1. 安装依赖

```bash
cd /path/to/aqicn_mcp
pip install -e .
```

### 2. 获取 API Token

访问 [AQICN API](https://aqicn.org/api/) 注册并获取免费的 API token。

### 3. 测试 API 连接

```bash
python test_aqicn.py
```

## 配置 MCP

### 配置内容

在配置文件的 `mcpServers` 部分添加以下内容：

```json
{
  "mcpServers": {
    "aqicn": {
      "command": "python",
      "args": [
        "/path/to/aqicn_mcp/src/aqicn_mcp/server.py"
      ],
      "env": {
        "AQICN_TOKEN": "your_token_here"
      }
    }
  }
}
```

**重要提示**：
- 将 `/path/to/aqicn_mcp` 替换为实际的项目绝对路径
- 将 `your_token_here` 替换为你在 AQICN 获取的实际 API token

## 使用方法示例

```
查询北京的空气质量
```

```
上海今天的 AQI 是多少
```

```
深圳的空气污染情况怎么样
```

```
帮我看一下杭州的空气质量
```

## 返回数据说明

查询结果包含以下信息：

- **AQI 指数**: 空气质量指数（0-500+）
- **空气质量等级**: 优、良、轻度污染、中度污染、重度污染、严重污染
- **健康建议**: 针对当前空气质量等级的健康建议
- **污染物详情**:
  - PM2.5: 细颗粒物
  - PM10: 可吸入颗粒物
  - 二氧化硫 (SO2)
  - 二氧化氮 (NO2)
  - 臭氧 (O3)
  - 一氧化碳 (CO)
  - 颗粒物 (P)
- **更新时间**: 数据的更新时间戳

## API 信息

- **API 提供商**: World Air Quality Index Project
- **官方网站**: https://aqicn.org/api/
- **免费额度**: 1000次请求/秒
- **数据更新频率**: 每小时更新一次
- **数据来源**: 全球各地环保部门监测站

## 许可和使用条款

使用本 MCP 服务器需要遵守 AQICN API 的使用条款：

- 数据不可用于商业付费应用
- 免费使用，但需遵守 API 调用限制
- 详见: https://aqicn.org/api/

## 故障排除

### MCP 服务器无法启动
- 检查 Python 路径是否正确
- 确认已安装所有依赖: `pip install -e .`
- 检查 AQICN_TOKEN 是否正确设置

### 查询失败
- 验证 API token 是否有效
- 检查网络连接
- 确认城市拼音拼写正确
- 查看 API 是否在正常服务

## 项目结构

```
aqicn_mcp/
├── src/aqicn_mcp/
│   ├── __init__.py
│   └── server.py          # MCP 服务器主程序
├── test_aqicn.py           # API 测试脚本
├── README.md               # 项目文档
└── pyproject.toml          # 项目配置
```

## 技术栈

- Python 3.8+
- MCP SDK (Model Context Protocol)
- httpx (异步 HTTP 客户端)
- AQICN API

## 贡献

欢迎提交 Issue 和 Pull Request！

## 许可证

MIT License