# Weather MCP Server

基于 [和风天气](https://www.qweather.com/) API 的 **Model Context Protocol (MCP)** 服务器，让 Claude / Cursor / Cline 等 MCP 客户端能够查询中国城市的实时天气、预报和预警。

## ✨ 功能特性

| 工具 | 功能 | 输入 |
|---|---|---|
| `get_current_weather` | 查询实时天气 | 城市名 / 经纬度 / Location ID |
| `get_forecast` | 查询未来 3/7/10/15/30 天天气预报 | 城市名 + 天数 |
| `get_warnings` | 查询当前生效中的气象灾害预警 | 城市名 / 经纬度 / Location ID |

- 🔒 **API Key 不入源码**——通过环境变量或 `.mcp.json` 注入
- 🌍 **GeoAPI 自动解析**——支持「北京」「上海」等中文城市名，也支持 `116.41,39.92` 经纬度
- 📐 **公制 / 英制可切换**——`get_current_weather` 支持 `unit=m/i` 参数
- 🌐 **多语言**——支持 `lang=zh/en/...`

## 🚀 快速开始

### 1. 获取和风天气 API Key

前往 [和风天气控制台](https://console.qweather.com/) → 注册 → 创建项目 → 拿到 API Key（推荐重置一次以确保 Key 安全）。

### 2. 准备环境

需要 [uv](https://docs.astral.sh/uv/)（推荐）或 Python 3.10+。

```bash
# 克隆 / 进入项目目录
cd F:\code\weather

# 同步依赖
uv sync
```

### 3. 配置环境变量

将 Key 写入 `.mcp.json`（推荐，详见下方 MCP 客户端配置）或系统环境变量：

```bash
# PowerShell
$env:WEATHER_API_KEY = "你的key"

# Bash
export WEATHER_API_KEY="你的key"
```

### 4. 测试连通性

```bash
uv run weather.py
```

服务器启动后会在 stdio 上等待 MCP 客户端连接，不会自己产生输出——这是正常行为。

## ⚙️ 配置

### API Host

[weather.py:7](weather.py#L7) 中配置的是**专属子域名**，使用 `X-QW-Api-Key` 请求头鉴权：

```python
QWEATHER_HOST = "https://<your-sub>.re.qweatherapi.com"
```

如需改回公共域名（`devapi.qweather.com` / `geoapi.qweather.com`），将 host 替换即可，鉴权方式相应改为 URL `?key=` 参数。

### 环境变量

| 变量名 | 必填 | 说明 |
|---|---|---|
| `WEATHER_API_KEY` | ✅ | 和风天气 API Key |

## 🔌 MCP 客户端配置

### Claude Code（项目级，推荐）

新建 [`.mcp.json`](.mcp.json)：

```json
{
  "mcpServers": {
    "weather": {
      "command": "uv",
      "args": ["run", "weather.py"],
      "env": {
        "WEATHER_API_KEY": "你的key"
      }
    }
  }
}
```

重启 Claude Code 后，在对话中输入 `/mcp` 应能看到 `weather: connected · 3 tools`。

### Claude Desktop

编辑 `%APPDATA%\Claude\claude_desktop_config.json`：

```json
{
  "mcpServers": {
    "weather": {
      "command": "uv",
      "args": ["--directory", "F:\\code\\weather", "run", "weather.py"],
      "env": { "WEATHER_API_KEY": "你的key" }
    }
  }
}
```

### MCP Inspector（调试用）

```bash
uv run --with "mcp[cli]" mcp dev weather.py
```

会自动打开浏览器调试控制台。

## 💬 使用示例

在配置好 MCP 的客户端中直接用自然语言提问：

```
杭州今天天气怎么样？
上海未来 7 天天气预报
北京有没有台风预警？
116.41, 39.92 这个坐标的天气
用英制单位查东京当前天气
```

LLM 会自动选择并调用合适的工具。

## 📁 项目结构

```
weather/
├── .mcp.json            # Claude Code MCP 配置
├── .python-version      # Python 版本声明（3.10）
├── .venv/               # 虚拟环境（uv 管理）
├── .gitignore
├── pyproject.toml       # 项目元数据 + 依赖
├── uv.lock              # 锁定依赖版本
├── main.py              # 入口占位（未使用）
├── weather.py           # ⭐ MCP 服务器主程序
└── README.md            # 本文件
```

## 🛠️ 开发

### 依赖

| 包 | 版本 | 用途 |
|---|---|---|
| `httpx` | ≥ 0.28.1 | 异步 HTTP 客户端 |
| `mcp[cli]` | ≥ 1.28.1 | MCP 协议 SDK |

### 添加工具

在 [weather.py](weather.py) 中用 `@mcp.tool()` 装饰器注册新函数：

```python
@mcp.tool()
async def my_new_tool(arg: str) -> str:
    """工具描述（LLM 据此决定何时调用）。"""
    ...
```

### 接口规范适配进度

| 接口 | 状态 |
|---|---|
| `/v7/weather/now` 实时天气 | ✅ 按规范展开全字段 |
| `/v7/weather/{3,7,10,15,30}d` 天气预报 | 🟡 基本功能，待按规范补字段 |
| `/v7/warning/now` 天气预警 | 🟡 基本功能，待按规范补字段 |
| `/geo/v2/city/lookup` 城市解析 | 🟡 仅返回 Location ID，未暴露其他字段 |

## ⚠️ 安全提示

- **永远不要把 API Key 硬编码进源码**——使用环境变量或 `.mcp.json` 的 `env` 字段
- **不要把 `.mcp.json` 提交到公开仓库**——如果必须提交，把 Key 改成环境变量占位符
- 泄露的 Key 应立即去和风天气控制台**重置**

## 📝 License

MIT