# AMap Weather MCP

一个基于高德地图 API 的 MCP（Model Context Protocol）服务器，提供实时天气查询和城市代码搜索功能。

## 功能特性

- 🌤️ **实时天气查询** - 支持按城市名称或城市代码查询天气信息
- 📍 **城市搜索** - 支持精确匹配和模糊搜索中国所有城市
- 📊 **4日天气预报** - 获取详细的天气预报数据
- 🔄 **多种查询方式**：
  - 按城市名称查询（如：杭州市、北京市）
  - 按行政代码（adcode）查询
  - 列出所有可用城市
  - 按 adcode 获取城市信息

## 系统需求

- Python 3.8+
- 高德地图 API 密钥（[申请教程](https://amap.apifox.cn/doc-7445538)）

## 安装

### 1. 克隆或下载项目

```bash
git clone <repository-url>
cd amap-weather-mcp
```

### 2. 安装依赖

使用 `uv` 包管理器（推荐）：

```bash
uv pip install -r requirements.txt
```

或使用 pip：

```bash
pip install -r requirements.txt
```

## 配置

### 环境变量

需要配置以下环境变量：

| 环境变量 | 说明 | 必需 |
|---------|------|------|
| `AMAP_API_KEY` | 高德地图 API 密钥 | ✅ 必需 |

### 使用 Claude Desktop 集成(或者使用其他方式)

将以下配置添加到 Claude Desktop 的 `claude_desktop_config.json`：

```json
{
    "mcpServers": {
        "amap-weather-mcp": {
            "name": "amap-weather-mcp",
            "type": "stdio",
            "isActive": true,
            "command": "uv",
            "args": [
                "--directory",
                "/path/to/amap-weather-mcp",
                "run",
                "main.py"
            ],
            "env": {
                "AMAP_API_KEY": "your-api-key-here"
            }
        }
    }
}
```

## 使用方式

### 可用工具

#### 1. `get_weather_by_city_name`
按城市名称获取天气信息

**参数：**
- `city_name` (string): 城市名称，如 "杭州市"、"北京市"

**返回：** 实时天气和 4 天预报数据

#### 2. `get_weather_by_city_code`
按城市行政代码获取天气信息

**参数：**
- `city_code` (string): 城市行政代码，如 "110100"（北京市朝阳区）

**返回：** 实时天气和 4 天预报数据

#### 3. `search_city`
搜索城市（支持精确和模糊匹配）

**参数：**
- `city_name` (string): 要搜索的城市名称

**返回：** 匹配的城市列表及其代码

#### 4. `get_city_by_adcode`
按 adcode 获取城市信息

**参数：**
- `adcode` (string): 行政代码，如 "110000"（北京市）

**返回：** 城市信息对象

#### 5. `list_all_cities`
列出所有可用城市

**参数：**
- `limit` (integer): 返回结果数量限制，默认 50，最大 200

**返回：** 城市列表，包括总数量

## 项目结构

```
amap-weather-mcp/
├── main.py                 # 主程序文件
├── city_codes.json        # 城市代码数据库
├── requirements.txt       # 项目依赖
├── .gitignore            # Git 忽略规则
└── README.md             # 本文件
```

## 依赖包

- `httpx` - 异步 HTTP 客户端
- `requests` - HTTP 库
- `mcp` - Model Context Protocol 实现

## 开发说明

### 项目特点

- 使用 Python `asyncio` 实现异步操作
- 集成 MCP 标准，支持与 Claude AI 无缝集成
- 高效的城市代码索引，支持快速查询
- 完善的错误处理和日志记录

### 日志

程序使用 Python 的 `logging` 模块记录信息，日志级别为 INFO。

## 许可证

MIT License

## 支持

如有问题或建议，欢迎提交 Issue 或 Pull Request。