和风天气 MCP 服务

一个基于 Model Context Protocol (MCP) 的和风天气服务，提供天气预报、气象预警、空气质量、历史数据、天文信息、热带气旋 (台风) 等多种气象数据查询功能。

功能特性

• 天气预报: 获取3-30天详细天气预报（支持3d/7d/10d/15d/30d）
• GeoAPI服务: 热门城市查询、POI搜索和范围搜索功能
• 空气质量扩展: 空气质量小时/日预报、监测站污染物数据查询
• 格点天气: 全球任意坐标高分辨率数值预报天气（3-5公里分辨率）
• 热带气旋 (台风): 台风列表、实况路径和预报路径查询（支持西北太平洋流域）
• 气象预警: 查询实时气象灾害预警信息
• 生活指数: 获取各类生活指数预报，如洗车、穿衣、感冒等（16种指数）
• 空气质量: 获取城市的空气质量指数（AQI）及主要污染物信息
• 逐小时预报: 获取未来 24/72/168 小时逐小时天气（温度、天气状况、风力/风速/风向、相对湿度、气压、降水概率、露点、云量等）
• 实况天气: 获取近实时天气（温度、体感温度、风、湿度、气压、降水量、能见度、露点、云量等）
• 历史数据: 获取历史天气和空气质量数据（最多10天）
• 天文数据: 获取日出日落时间、月相月升月落信息
• 分钟级预报: 获取未来2小时5分钟级降水预报
• 双认证支持: 支持 API KEY 和 JWT + EdDSA 数字签名认证
• 详细日志: 完整的操作日志和错误处理

安装

uv tool install hefeng-qweather-mcp

或使用 pip 安装：

pip install hefeng-qweather-mcp

# 推荐配置 - API KEY 认证（简单快捷）
HEFENG_API_HOST=你的API主机地址
HEFENG_API_KEY=你的API KEY

# 备用配置 - JWT 数字签名认证
# HEFENG_PROJECT_ID=你的项目ID
# HEFENG_KEY_ID=你的凭据ID
# HEFENG_PRIVATE_KEY_PATH=./ed25519-private.pem

# 可选：直接加载密钥内容，方便远程部署
# HEFENG_PRIVATE_KEY=

使用

快速开始

1. 配置环境变量

   # 复制并编辑配置文件
   cp .env.example .env

   # 填入您的和风天气 API 配置
   # 推荐使用 API KEY 认证方式

服务启动时会按以下优先级自动查找 .env 配置文件（已加载的变量不会被后续文件覆盖）：

用户级路径遵循 XDG 规范：若设置了 XDG_CONFIG_HOME 环境变量，则查找 $XDG_CONFIG_HOME/qweather/.env。

1. 启动服务器

   # STDIO 模式（推荐用于本地开发）
   hefeng-qweather-mcp stdio

   # HTTP 模式（推荐用于远程访问）
   hefeng-qweather-mcp http

运行模式

#### HTTP 模式

HTTP 模式提供 Web API 接口，适合远程访问和 Web 集成：

hefeng-qweather-mcp http

服务器启动后将在 http://127.0.0.1:8000 运行，MCP 端点为 http://127.0.0.1:8000/mcp。

VS Code 配置：

{
  "servers": {
    "hefeng-qweather-mcp": {
      "url": "http://127.0.0.1:8000/mcp",
      "type": "http"
    }
  },
  "inputs": []
}

#### STDIO 模式

STDIO 模式通过标准输入输出通信，适合本地开发：

hefeng-qweather-mcp stdio

VS Code 配置：

{
  "servers": {
    "hefeng-qweather-mcp": {
      "type": "stdio",
      "command": "hefeng-qweather-mcp stdio"
    }
  },
  "inputs": []
}

使用 uv 运行：

{
  "servers": {
    "hefeng-qweather-mcp": {
      "type": "stdio",
      "command": "uvx hefeng-qweather-mcp stdio",
      "envFile": "${workspaceFolder}/.env"
    }
  },
  "inputs": []
}

管理服务器

#### 查看运行状态

# 查看后台进程
ps aux | grep hefeng-qweather-mcp

#### 停止服务器

# 停止所有模式
pkill -f hefeng-qweather-mcp

# 或分别停止
pkill -f "hefeng-qweather-mcp stdio"
pkill -f "hefeng-qweather-mcp http"

#### 验证配置

服务启动后，可以通过以下方式验证配置是否正确：

1. 检查日志输出 - 确认 API 主机和认证信息正确显示
2. 在 VS Code 中测试 - 使用 MCP 工具查询天气数据
3. 检查服务状态 - 确保服务正常运行无错误

如果遇到配置问题，请检查：

• 环境变量是否正确设置
• API KEY 是否有效且未过期
• 网络连接是否正常

使用示例

#### 天文数据查询示例

# 查询北京今天的日出日落时间
get_astronomy_sun("北京", "20251029")
# 结果：日出 06:40, 日落 17:17

# 查询上海的月相信息
get_astronomy_moon("上海", "20251101")
# 结果：月升 13:24, 月落 23:09, 月相：上弦月

# 使用经纬度查询（全球任意地点）
get_astronomy_sun("116.41,39.92", "20251029")  # 北京坐标
get_astronomy_moon("121.47,31.23", "20251101")  # 上海坐标

# 查询未来日期的天文数据
get_astronomy_sun("广州", "20251225")  # 圣诞节
get_astronomy_moon("深圳", "20260101")  # 元旦

#### 多天天气预报示例

# 查询不同天数的天气预报
get_weather("北京", "3d")   # 3天预报（默认）
get_weather("上海", "7d")   # 7天预报
get_weather("广州", "15d")  # 15天预报
get_weather("深圳", "30d")  # 30天预报

#### GeoAPI功能示例

# 获取热门城市列表
get_top_cities(10, "cn")  # 获取10个中国热门城市

# POI关键词搜索（米制半径）
search_poi("116.41,39.92", "故宫", "scenic", radius=10000)

# POI范围搜索（公里制半径）
search_poi_range("116.41,39.92", "scenic", radius=2)  # 2公里范围内景点

# 搜索餐厅和其他类型POI
search_poi("北京", "火锅", "scenic", radius=5000)  # 北京5公里内的景点

#### 空气质量扩展功能示例

# 空气质量小时预报
get_air_quality_hourly("39.92,116.41", "24h")  # 24小时逐小时空气质量
get_air_quality_hourly("39.92,116.41", "72h")  # 72小时逐小时空气质量

# 空气质量每日预报
get_air_quality_daily("39.92,116.41", "3d")     # 3天空气质量预报

# 监测站数据查询
get_air_quality_stations("P58911")  # 查询监测站P58911的污染物数据
get_air_quality_stations("P53763")  # 查询监测站P53763的污染物数据

#### 热带气旋 (台风) 功能示例

# 获取2020年西北太平洋台风列表
get_storm_list("2020")
# 返回: {"code": "200", "storm": [{"id": "NP2008", "name": "巴威", ...}]}

# 获取指定台风的实况和路径
get_storm_track("NP2018")
# 返回: {"code": "200", "isActive": "1", "now": {...}, "track": [...]}

# 获取指定台风的预报路径
get_storm_forecast("NP2018")
# 返回: {"code": "200", "forecast": [{...}]}

# 注意：当前仅支持 basin=NP（西北太平洋），其他流域暂不可用
# 台风列表仅支持本年度和上一年度查询

可用的 MCP 工具

您的 MCP 服务器提供以下天气查询工具：

#### 基础天气工具

• `get_weather_now` - 获取实时天气数据
• 参数：city（城市名）或 location（位置ID/坐标）
• 返回：温度、体感温度、天气状况、湿度、气压等

• `get_weather` - 获取天气预报
• 参数：city（城市名）、days（预报天数：3d/7d/10d/15d/30d，默认3d）
• 返回：指定天数的每日天气详情

• `get_hourly_weather` - 获取逐小时天气预报
• 参数：hours（24h/72h/168h）、city 或 location
• 返回：逐小时温度、天气、风力、湿度等

#### 空气质量工具

• `get_air_quality` - 获取实时空气质量
• 参数：city（城市名）
• 返回：AQI、污染物浓度、健康建议

• `get_air_quality_history` - 获取历史空气质量
• 参数：city（城市名）、days（1-10天）
• 返回：历史空气质量数据

#### 生活指数工具

• `get_indices` - 获取生活指数预报
• 参数：city（城市名）、days（1d/3d）、index_types（指数类型）
• 返回：16种生活指数（运动、洗车、穿衣、感冒等）

#### 预警和天文工具

• `get_warning` - 获取气象预警信息
• 参数：city（城市名）
• 返回：实时气象灾害预警

• `get_astronomy_sun` - 获取日出日落时间
• 参数：location（城市名/LocationID/坐标）、date（yyyyMMdd格式，支持未来60天）
• 返回：日出日落时间（支持全球任意地点）

• `get_astronomy_moon` - 获取月相和月升月落信息
• 参数：location（城市名/LocationID/坐标）、date（yyyyMMdd格式，支持未来60天）
• 返回：月升月落时间、24小时逐小时月相数据（含月相名称、照明度）

#### 历史和详细数据工具

• `get_weather_history` - 获取历史天气数据
• 参数：city 或 location、days（1-10天）
• 返回：历史天气数据

• `get_minutely_5m` - 获取分钟级降水预报
• 参数：location（坐标或城市名）
• 返回：未来2小时5分钟级降水数据

#### GeoAPI工具（新功能）

• `get_top_cities` - 获取热门城市列表
• 参数：number（返回数量，默认10）、city_type（城市类型：cn/world/overseas，默认cn）
• 返回：热门城市列表，包含ID、坐标、时区等信息

• `search_poi` - POI关键词搜索
• 参数：location（位置）、keyword（搜索关键词）、poi_type（POI类型：scenic/TSTA）、radius（搜索半径，米制，100-50000）
• 返回：搜索到的兴趣点列表，包含详细位置信息

• `search_poi_range` - POI范围搜索
• 参数：location（中心坐标）、poi_type（POI类型：scenic/TSTA）、radius（搜索半径，公里制，1-50）
• 返回：指定范围内的兴趣点，按距离排序

#### 空气质量扩展工具（新功能）

• `get_air_quality_hourly` - 获取空气质量小时预报
• 参数：location（纬度,经度坐标）、hours（预报时长：24h/72h/168h）、lang（语言，默认zh）
• 返回：逐小时空气质量数据，包含AQI、污染物浓度、健康建议

• `get_air_quality_daily` - 获取空气质量每日预报
• 参数：location（纬度,经度坐标）、days（预报天数：3d）、lang（语言，默认zh）
• 返回：每日空气质量预报，包含AQI趋势和主要污染物

• `get_air_quality_stations` - 获取空气质量监测站数据
• 参数：station_id（监测站ID，如P58911）、lang（语言，默认zh）
• 返回：监测站污染物浓度数据，包含各类污染物的实时浓度值

#### 格点天气工具

• `get_grid_weather_now` - 获取格点实时天气数据
• 参数：location（经纬度坐标）、lang（语言，默认zh）、unit（单位，默认m）
• 返回：高分辨率（3-5公里）实时天气数据，支持全球任意坐标

• `get_grid_weather_daily` - 获取格点每日天气预报
• 参数：location（经纬度坐标）、lang（语言，默认zh）、unit（单位，默认m）
• 返回：格点数值模式的每日天气预报

• `get_grid_weather_hourly` - 获取格点逐小时天气预报
• 参数：location（经纬度坐标）、lang（语言，默认zh）、unit（单位，默认m）
• 返回：格点数值模式的逐小时天气预报

#### 热带气旋 (台风) 工具（新功能）

• `get_storm_list` - 获取台风列表
• 参数：year（年份，如 '2020'，仅支持本年度和上一年度）、basin（流域，默认 'NP' 西北太平洋）
• 返回：台风列表，包含台风ID、名称、流域、年份、是否活跃等信息

• `get_storm_track` - 获取台风实况和路径
• 参数：stormid（台风ID，可通过 get_storm_list 获取，如 'NP2018'）
• 返回：台风实时位置、等级、气压、风速、历史轨迹路径
• 注意：如台风已结束，now 字段可能为 null

• `get_storm_forecast` - 获取台风预报路径
• 参数：stormid（台风ID，如 'NP2018'）
• 返回：台风预报位置、等级、气压、风速等
• 注意：如台风已结束，预报数据可能为空，建议先通过 get_storm_list 获取台风状态

前置要求

• Python >= 3.11
• OpenSSL (用于生成密钥对)
• 和风天气开发者账号

开发

1. 克隆项目

git clone https://github.com/fengyucn/hefeng-qweather-mcp.git
cd hefeng-qweather-mcp

2. 安装依赖

使用 pip:

pip install -e .

或使用 uv (推荐):

uv sync

3. 获取和风天气 API 配置

#### 方式一：API KEY 认证（推荐）

1. 访问 和风天气控制台
2. 注册/登录账号
3. 创建项目并获取 API KEY
4. 复制配置模板文件：

cp .env.example .env

1. 编辑 .env 文件：

# API KEY 认证配置
HEFENG_API_HOST=你的API主机地址
HEFENG_API_KEY=你的API KEY

通过 pip/uv 安装后，也可以将 .env 放在 ~/.config/qweather/ 目录作为用户级配置（详见「快速开始」中的配置查找优先级）。

#### 方式二：JWT 数字签名认证（备用）

如果需要使用 JWT 认证：

1. 在和风天气控制台创建项目并记录 Project ID
2. 生成 EdDSA 密钥对：

openssl genpkey -algorithm ED25519 -out ed25519-private.pem \
&& openssl pkey -pubout -in ed25519-private.pem > ed25519-public.pem

1. 在控制台中创建数字签名凭据，上传公钥文件
2. 配置 .env 文件：

# JWT 认证配置
HEFENG_API_HOST=你的API主机地址
HEFENG_PROJECT_ID=你的项目ID
HEFENG_KEY_ID=你的凭据ID
HEFENG_PRIVATE_KEY_PATH=./ed25519-private.pem

注意： 推荐优先使用 API KEY 认证，配置更简单。JWT 认证适合需要更高安全性的场景。

开发指南

1. 代码风格: 项目使用 ruff 进行代码格式化和检查
2. 类型检查: 使用 mypy 进行静态类型检查
3. 测试: 建议为新功能添加相应的单元测试
4. 文档: 确保所有新功能都有详细的 docstring 文档

版本历史

v1.2.0 (最新)

• ✅ 新增用户级配置文件支持：~/.config/qweather/.env（XDG 规范，可用 XDG_CONFIG_HOME 覆盖）

v1.1.0

• ✅ 新增热带气旋 (台风) API 服务模块
• ✅ 新增 get_storm_list: 台风列表查询（支持指定流域和年份）
• ✅ 新增 get_storm_track: 台风实况和路径（实时位置、等级、气压、风速、历史轨迹）
• ✅ 新增 get_storm_forecast: 台风预报路径（预测位置、等级、气压、风速）
• ✅ 支持 NP 西北太平洋流域，当前仅支持本年度和上一年度查询
• ✅ 完善参数验证、错误处理和中文文档字符串

v1.0.0

• ✅ 项目进入生产稳定阶段
• ✅ 完善所有API的参数验证和错误处理
• ✅ 统一代码风格和文档规范

v0.5.0

• ✅ 新增GeoAPI服务：热门城市查询、POI搜索和范围搜索
• ✅ 新增空气质量扩展：小时/日预报、监测站污染物数据查询
• ✅ POI搜索支持关键词和范围两种模式，支持景点和潮汐站点类型
• ✅ 空气质量预报支持24/72/168小时逐小时预报和3天日预报
• ✅ 监测站数据提供实时污染物浓度值，支持精确的监测站ID查询
• ✅ 修复API参数格式和文档不一致问题，统一参数验证机制

v0.4.0

• ✅ 新增格点天气接口：高分辨率数值预报天气查询
• ✅ 支持全球任意坐标的实时天气查询（3-5公里分辨率）
• ✅ 新增格点每日天气预报和逐小时天气预报
• ✅ 基于数值预报模型，提供精确坐标天气数据
• ✅ 完善多语言支持和单位选择功能

v0.3.0

• ✅ 新增天文数据接口：日出日落时间和月相月升月落
• ✅ 新增分钟级降水预报接口（未来2小时5分钟级）
• ✅ 支持多种天气预报时长：3d/7d/10d/15d/30d
• ✅ 支持24/72/168小时逐小时天气预报
• ✅ 完善历史数据查询（天气和空气质量，最多10天）
• ✅ 优化认证系统，优先使用API KEY认证
• ✅ 完善错误处理和日志记录

v0.2.1

• 基础天气查询功能
• JWT数字签名认证支持
• 空气质量查询
• 生活指数查询

许可证

MIT License

贡献指南

我们欢迎任何形式的贡献！

提交 Issue

如果你发现了 bug 或有功能建议，请：

1. 查看现有的 Issue，避免重复提交
2. 使用清晰的标题和详细的描述
3. 如果是 bug 报告，请包含重现步骤和环境信息

相关链接

• 和风天气官网
• 和风天气开发者控制台
• 和风天气 API 文档
• Model Context Protocol
• 更新日志

联系方式

如有问题或建议，请通过以下方式联系：

• 🐛 Issues: GitHub Issues
• 💬 讨论: GitHub Discussions

免责声明: 本项目仅供学习和研究使用，请遵守和风天气的服务条款和 API 使用规范。