# 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。
