Hefeng Qweather MCP Git

合丰气象MCP服务

基于模型上下文协议（MCP）的合丰天气服务，提供各种气象数据查询功能，如天气预报、气象预警、空气质量、历史数据和天文信息。

特性

• 天气预报：获取3-30天的详细天气预报（支持3d/7d/10d/15d/30d）
• 气象警告：查询实时气象灾害预警信息
• 生命指数：获取各种生活指数预测，如洗车、穿衣、感冒等。（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 认证方式

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代码配置：

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

STDIO模式

STDIO模式通过标准输入和输出进行通信，适用于本地开发：

hefeng-qweather-mcp stdio

VS代码配置：

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

使用紫外线运行：

{
  "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代码测试 -使用MCP工具查询天气数据
3. 检查服务状态 -确保服务运行无错误

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

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

用法示例

天文数据查询示例

# 查询北京今天的日出日落时间

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天预报

可用的MCP工具

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

基本天气工具

• get_weather_now -获取实时天气数据

- 参数： city （城市名称）或 location （位置ID/坐标） - 返回值：温度、感知温度、天气条件、湿度、压力等。

• get_weather -获取天气预报

- 参数： city （城市名称）， days （预测天数：3d/7d/10d/15d/30d，默认3d） - 返回：指定天数的每日天气详细信息

• get_hourly_weather -获取每小时天气预报

- 参数： hours （24小时/72小时/168小时）， city 或 location - 返回：每小时温度、天气、风力、湿度等。

空气质量工具

• get_air_quality -获取实时空气质量

- 参数： city （城市名称） - 返回：空气质量指数、污染物浓度、健康建议

• get_air_quality_history -获取历史空气质量

- 参数： city （城市名称）， days （1-10天） - 返回：历史空气质量数据

生命指数工具

• get_indices -获取生命指数预测

- 参数： city （城市名称）， days （1d/3d）， index_types （索引类型） - 回报：16种生活指标（运动、洗车、穿衣、感冒等）

警告和天文工具

• get_warning -获取气象预警信息

- 参数： city （城市名称） - 返回：实时气象灾害预警

• get_astronomy_sun -获取日出和日落时间-参数： location （城市名称/LocateID/坐标）， date （yyyyMMdd格式，支持未来最多60天）

• 返回：日出和日落时间（支持全球任何地点）

• get_astronomy_moon -获取月相和月升/月落信息

- 参数： location （城市名称/LocateID/坐标）， date （yyyyMMdd格式，支持未来最多60天） - 返回：月亮升起和落下的时间，24小时的每小时月相数据（包括月相名称和照度）

历史和详细数据工具

• get_weather_history -获取历史天气数据

- 参数： city 或 location, days （1-10天） - 返回：历史天气数据

• get_minutely_5m -获取分钟级降水预报

- 参数： location （坐标或城市名称） - 返回：未来2小时的5分钟水平降水数据

先决条件

• Python>=3.11
• OpenSSL（用于生成密钥对）
• Heweather开发者账号

发展

1.克隆项目

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

cd hefeng-qweather-mcp

2.安装依赖项

使用pip：

pip install -e .

或使用紫外线（推荐）：

uv sync

3.获取Heweather API配置

方法一：API密钥认证（推荐）

1. 访问 Heweather控制台
2. 注册/登录您的帐户
3. 创建一个项目并获得 API密钥
4. 复制配置模板文件：

cp .env.example .env

1. 编辑 .env 文件：

# API KEY 认证配置

HEFENG_API_HOST=你的API主机地址

HEFENG_API_KEY=你的API KEY

方法二：JWT数字签名认证（备选）

如果您需要使用JWT身份验证：

1. 在Heweather控制台中，创建一个项目并记录 项目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.3.0（最新版本）

• ✅ 新增天文数据接口：日出/日落时间和月相、月升/月落
• ✅ 新增分钟级降水预报界面（未来2小时5分钟级）
• ✅ 支持多种天气预报持续时间：3d/7d/10d/15d/30d
• ✅ 支持24/72/168小时的天气预报
• ✅ 改进了历史数据查询（天气和空气质量，最多10天）
• ✅ 优化认证系统，优先考虑API密钥认证
• ✅ 增强的错误处理和日志记录

v0.2.1

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

许可证

MIT许可证

贡献指南

我们欢迎任何形式的捐款！

提交问题

如果您发现错误或有功能建议，请：

1. 检查现有问题以避免重复
2. 使用清晰的标题并提供详细的描述
3. 如果是错误报告，包括重现步骤和环境信息

相关链接

• Heweather官方网站
• Heweather开发者控制台
• Heweather API文档
• 模型上下文协议

联系

如有疑问或建议，请通过以下渠道联系我们：

• 🐛 问题：
• 💬 讨论：

______________________________________________________________________

免责声明：本项目仅用于学习和研究目的。请遵守Hewether的服务条款和API使用指南。