gandli/Weather-MCP-Server

Weather MCP Server

一个基于 FastMCP 的和风天气（QWeather）查询服务，提供以下工具：

• lookup_city(location): 城市/位置查询（名称或经纬度）
• get_warning(location): 天气预警查询（LocationID 或经纬度）
• get_forecast(location): 当前天气查询（LocationID 或经纬度）

上述工具通过 MCP 的 stdio 传输暴露给客户端（编辑器、CLI 等）。

环境要求

• Python >= 3.13
• 依赖：httpx, mcp[cli], python-dotenv

配置

本项目使用 .env 读取和风天气配置：

在项目根目录创建 .env 文件并填入：

QWEATHER_API_HOST=your_api_host
QWEATHER_API_KEY=your_api_key

说明：

• QWEATHER_API_HOST 应为域名，不包含协议（示例：your_api_host），最终请求将拼接为 https://{HOST}/...。
• QWEATHER_API_KEY 为和风天气控制台申请的密钥。

安装与运行

克隆仓库：

git clone --depth 1 https://github.com/gandli/Weather-MCP-Server

使用 uv 进行依赖同步与运行：

• 同步依赖：

  • uv pip sync pyproject.toml

• 直接运行（作为 MCP 服务器，使用 stdio，会等待客户端连接）：

  • uv run .\main.py

• 安装脚本入口并运行：

  • uv pip install -e .
  • weather-mcp

脚本入口在 pyproject.toml 中注册为：

[project.scripts]
weather-mcp = "main:main"

MCP 集成

• 入口函数：main:main
• 传输方式：stdio
• 客户端（编辑器或 CLI）需要以 stdio 方式启动此服务器并与其通信。

客户端配置示例（JSON）

在支持 MCP 的客户端中，可添加如下配置以 stdio 方式启动本服务：

{
  "mcpServers": {
    "weather": {
      "name": "weather",
      "type": "stdio",
      "description": "一个基于 FastMCP 的和风天气（QWeather）查询服务",
      "isActive": true,
      "registryUrl": "",
      "command": "uv",
      "args": [
        "--directory",
        "c:\\Users\\ic\\Desktop\\weather",
        "run",
        "main.py"
      ]
    }
  }
}

说明：

• 使用 uv 的 --directory 指定项目根目录，随后运行 main.py 以启动 MCP 服务器（stdio）。
• 若已安装脚本入口（weather-mcp），也可将上述配置中的 command 改为 weather-mcp 并移除 args。
• Windows 路径在 JSON 字符串中需使用双反斜杠（示例已处理）。
• isActive: true 表示客户端会主动启动并连接该服务器。

可用工具与示例

lookup_city(location: str) -> str

查询城市信息并返回格式化文本。

• location：地区名称，或以英文逗号分隔的 经度,纬度（十进制，最多支持小数点后两位）。

示例（MCP 客户端侧调用）：

lookup_city("北京")

返回示例：

City: 北京
LocationID: 101010100
Latitude: 39.904
Longitude: 116.407

get_warning(location: str) -> str

查询天气预警并返回文本。

• location：LocationID 或 经度,纬度。

示例：

get_warning("116.40,39.90")

返回示例（无预警）：

暂无预警

返回示例（有预警）：

Title: 暴雨橙色预警
Type: 暴雨
Severity: 橙色
Time: 2025-01-01T12:00+08:00
Content: 预计未来3小时将出现强降雨，请注意防范。

get_forecast(location: str) -> str

获取指定位置的当前天气并返回文本。

• location：LocationID 或 经度,纬度。

示例：

get_forecast("116.40,39.90")

返回字段包含：UpdateTime, Link, ObsTime, Temp, FeelsLike, Text, WindDir, WindScale, WindSpeed, Humidity, Precip, Pressure, Visibility, Cloud, Dew, Sources, License。

常见问题（FAQ）

• 接口返回 接口错误 code: xxx：
  • 检查 QWEATHER_API_KEY 是否正确、是否有权限；
  • 检查 QWEATHER_API_HOST 是否为有效域名（例如 your_api_host）。
• 返回 暂无预警 或 暂无预报：
  • 表示当前地点暂未有预警或暂无当前天气数据；
  • 可尝试使用更精确的 LocationID 或经纬度。
• 在编写或扩展 MCP 工具时遇到 coroutine is not iterable：
  • MCP 工具函数均为 async def，注意对异步请求使用 await（例如：data = await make_nws_request(url)）。

许可

未设置专有许可证。如需开源协议，请在 pyproject.toml 或根目录添加相应许可文件。