# 天气查询 MCP 服务（Python 版）🌤

基于官方 [mcp](https://github.com/modelcontextprotocol/python-sdk) Python SDK（FastMCP）实现的天气查询 MCP 服务。
通过 **stdio** 与任何 MCP 客户端（如 Claude Desktop、WorkBuddy 等）通信，让 AI 助手能够实时查询指定城市的当前天气。

> 💡 天气数据来自 [Open-Meteo](https://open-meteo.com)，**无需注册、无需 API Key**。

## ✨ 功能特性

- ⚡ **纯 stdio 通信**：即插即用，无需开放端口、无需 HTTP 服务。
- 🌍 **多语言城市名**：支持中文与英文城市名，如 `北京`、`Beijing`、`Tokyo`。
- 🔒 **零密钥**：数据来自 Open-Meteo，不采集个人数据、不发送任何请求体。
- 🛡 **健壮的错误处理**：城市不存在、网络异常时返回友好中文提示而不会崩溃。
- 🎨 **友好的返回格式**：结构化文本 + emoji，便于客户端直接展示。

## 🛠 提供的工具

| 工具名        | 入参 | 说明 |
| ------------- | ---- | ---- |
| `get_weather` | `city`（城市名，支持中英文） | 返回该城市的实时天气：天气状况 / 温度 / 体感温度 / 湿度 / 风速 / 观测时间 |

### 返回示例

```
📍 北京（中国）当前天气
🌤  天气：晴
🌡  温度：27.3°C（体感 28.1°C）
💧 湿度：52%
🍃 风速：12.4 km/h
🕒 观测时间：2026-08-19T13:00
```

## 📋 环境要求

- Python **>= 3.10**（推荐 3.13，已在本机验证）
- 需要访问外网（调用 Open-Meteo API）

## 🚀 安装与运行

```bash
git clone https://github.com/<your-name>/weather-mcp-server-py.git
cd weather-mcp-server-py

# 创建虚拟环境（可选但推荐）
python3 -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate

# 安装依赖
pip install -r requirements.txt

# 运行（stdio 模式，通常由 MCP 客户端拉起）
python weather_server.py
```

> 本服务通过标准输入输出（stdio）与客户端通信，`python weather_server.py` 默认以 stdio 模式启动。

## 🔌 在 MCP 客户端中接入

以 Claude Desktop / WorkBuddy 的 `claude_desktop_config.json` / `mcp.json` 为例，添加如下配置
（请将 `python3` 替换为你机器上的解释器绝对路径，Windows 使用 `python.exe`）：

```json
{
  "mcpServers": {
    "weather": {
      "command": "python3",
      "args": ["/absolute/path/to/weather_server.py"]
    }
  }
}
```

保存并重启客户端后，即可在对话中请求“查询北京的天气”，模型会自动调用 `get_weather` 工具。

## 📁 项目结构

```
weather-mcp-server-py/
├── weather_server.py   # MCP 服务主实现（FastMCP）
├── requirements.txt    # 依赖清单
└── README.md           # 本说明
```

## 🧰 技术要点

- 城市 → 经纬度：使用 [Open-Meteo 地理编码接口](https://open-meteo.com/en/docs/geocoding-api)；
- 当前天气：使用 [Open-Meteo Forecast API](https://open-meteo.com/en/docs/)，`current` 字段一次性获取温度 / 体感 / 湿度 / 风速 / 天气代码；
- 天气代码 → 中文描述：内置 WMO 天气代码映射表；
- 运行时若网络不可用或找不到城市，均返回友好的中文错误提示，保证工具始终返回字符串。

## 🤝 贡献

欢迎提交 Issue 与 Pull Request，如补充更多天气指标、支持更多客户端示例或增加测试。

## 📄 License

[MIT](LICENSE) © 2026 yuxiaosen