和风天气 MCP 服务

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

功能特性

• 天气预报: 获取3-30天详细天气预报（支持3d/7d/10d/15d/30d）

• 格点天气: 全球任意坐标高分辨率数值预报天气（3-5公里分辨率）

• 气象预警: 查询实时气象灾害预警信息

• 生活指数: 获取各类生活指数预报，如洗车、穿衣、感冒等（16种指数）

• 空气质量: 获取城市的空气质量指数（AQI）及主要污染物信息

• 逐小时预报: 获取未来 24/72/168 小时逐小时天气（温度、天气状况、风力/风速/风向、相对湿度、气压、降水概率、露点、云量等）

• 实况天气: 获取近实时天气（温度、体感温度、风、湿度、气压、降水量、能见度、露点、云量等）

• 历史数据: 获取历史天气和空气质量数据（最多10天）

• 天文数据: 获取日出日落时间、月相月升月落信息

• 分钟级预报: 获取未来2小时5分钟级降水预报

• 双认证支持: 支持 API KEY 和 JWT + EdDSA 数字签名认证

• 详细日志: 完整的操作日志和错误处理

安装

或使用 pip 安装：

使用

快速开始

1. 配置环境变量

   # 复制并编辑配置文件 cp .env.example .env # 填入您的和风天气 API 配置 # 推荐使用 API KEY 认证方式

2. 启动服务器

   # STDIO 模式（推荐用于本地开发） hefeng-qweather-mcp stdio # HTTP 模式（推荐用于远程访问） hefeng-qweather-mcp http

运行模式

HTTP 模式

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

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

VS Code 配置：

STDIO 模式

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

VS Code 配置：

使用 uv 运行：

管理服务器

查看运行状态

停止服务器

验证配置

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

1. 检查日志输出 - 确认 API 主机和认证信息正确显示

2. 在 VS Code 中测试 - 使用 MCP 工具查询天气数据

3. 检查服务状态 - 确保服务正常运行无错误

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

• 环境变量是否正确设置

• API KEY 是否有效且未过期

• 网络连接是否正常

使用示例

天文数据查询示例

多天天气预报示例

可用的 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分钟级降水数据

格点天气工具（新功能）

• 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）

  • 返回：格点数值模式的逐小时天气预报

前置要求

• Python >= 3.11

• OpenSSL (用于生成密钥对)

• 和风天气开发者账号

开发

1. 克隆项目

2. 安装依赖

使用 pip:

或使用 uv (推荐):

3. 获取和风天气 API 配置

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

1. 访问 和风天气控制台

2. 注册/登录账号

3. 创建项目并获取 API KEY

4. 复制配置模板文件：

1. 编辑 .env 文件：

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

如果需要使用 JWT 认证：

1. 在和风天气控制台创建项目并记录 Project ID

2. 生成 EdDSA 密钥对：

3. 在控制台中创建数字签名凭据，上传公钥文件

4. 配置 .env 文件：

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

开发指南

1. 代码风格: 项目使用 ruff 进行代码格式化和检查

2. 类型检查: 使用 mypy 进行静态类型检查

3. 测试: 建议为新功能添加相应的单元测试

4. 文档: 确保所有新功能都有详细的 docstring 文档

版本历史

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 使用规范。