Skip to main content
Glama
fengyucn

Hefeng QWeather MCP Server

by fengyucn
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

和风天气 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 认证方式

  2. 启动服务器

    # 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的污染物数据

可用的 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）

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

前置要求

  • 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

方式二：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 文档

版本历史

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

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

Resources

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/fengyucn/hefeng-qweather-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server