# weather-mcp

一个用于查询天气的 **MCP（Model Context Protocol）** 服务，基于免费的 [Open-Meteo](https://open-meteo.com) 接口实现。

> ✅ **无需 API Key**　✅ 支持全球任意地点　✅ 实时天气 + 未来 16 天预报　✅ 中文输出

LLM 客户端（Claude Desktop、Cursor、Cline 等）接入后，就能直接用自然语言问"北京现在多少度""东京未来三天天气怎么样"。

---

## ✨ 功能

| 工具 | 说明 |
| --- | --- |
| `get_current_weather` | 查询指定地点的实时天气（温度、体感、天气状况、湿度、风、观测时间） |
| `get_weather_forecast` | 查询指定地点未来 1–16 天的逐日预报（天气、最高/最低温、降水） |

- 支持**城市名**（如 `北京`、`Shanghai`、`Tokyo`）或**经纬度**（如 `39.9,116.4`）
- 地点解析使用 Open-Meteo 地理编码接口，返回中文地名
- WMO 天气代码已映射为中文描述，风向转换为中文方位

---

## 📦 安装

要求 Python ≥ 3.10。

### 方式一：用 uv（推荐）

```bash
uv tool install weather-mcp
```

或直接从源码安装：

```bash
git clone https://github.com/your-username/weather-mcp.git
cd weather-mcp
uv pip install -e .
```

### 方式二：用 pip

```bash
git clone https://github.com/your-username/weather-mcp.git
cd weather-mcp
pip install -e .
```

也可以不安装、直接用 `requirements.txt`：

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

---

## 🔌 接入 MCP 客户端

### Claude Desktop

编辑配置文件（macOS：`~/Library/Application Support/Claude/claude_desktop_config.json`，Windows：`%APPDATA%\Claude\claude_desktop_config.json`）：

```json
{
  "mcpServers": {
    "weather": {
      "command": "weather-mcp"
    }
  }
}
```

如果是用 `pip install -r requirements.txt` 而非可编辑安装，请改用模块方式启动：

```json
{
  "mcpServers": {
    "weather": {
      "command": "python",
      "args": ["-m", "weather_mcp"]
    }
  }
}
```

> 💡 在 VS Code / Cursor 中若使用 `.venv`，把 `command` 指向虚拟环境里的 `python` 或脚本路径即可。

### Cursor / Cline / 其他支持 MCP 的客户端

配置方式类似，使用 stdio 传输，命令为 `weather-mcp`（或 `python -m weather_mcp`）。

---

## 🛠 本地开发

```bash
git clone https://github.com/your-username/weather-mcp.git
cd weather-mcp

# 创建虚拟环境并安装
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -e .

# 以开发模式运行（带可视化调试界面）
mcp dev src/weather_mcp/server.py

# 直接启动 stdio 服务
python -m weather_mcp
```

### 项目结构

```
weather-mcp/
├── pyproject.toml          # 打包配置（hatchling）+ 入口脚本
├── requirements.txt        # 运行依赖
├── README.md
├── LICENSE                 # MIT
├── .gitignore
└── src/
    └── weather_mcp/
        ├── __init__.py
        ├── __main__.py     # python -m weather_mcp 入口
        ├── server.py       # MCP 服务与工具定义（FastMCP）
        └── weather.py      # Open-Meteo 接口封装与解析
```

---

## 📝 示例

接入后，你可以直接在对话里问：

- "北京现在天气怎么样？"
- "帮我查一下上海未来 5 天的天气预报"
- "39.9,116.4 当前温度是多少？"

---

## 📄 许可证

[MIT](./LICENSE) © weather-mcp contributors