Weather MCP Server

基于 和风天气 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

前往 和风天气控制台 → 注册 → 创建项目 → 拿到 API Key（推荐重置一次以确保 Key 安全）。

2. 准备环境

需要 uv（推荐）或 Python 3.10+。

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

# 同步依赖
uv sync

3. 配置环境变量

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

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

# Bash
export WEATHER_API_KEY="你的key"

4. 测试连通性

uv run weather.py

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

⚙️ 配置

API Host

weather.py:7 中配置的是专属子域名，使用 X-QW-Api-Key 请求头鉴权：

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：

{
  "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：

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

MCP Inspector（调试用）

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 中用 @mcp.tool() 装饰器注册新函数：

@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