和风天气MCP服务

基于模型上下文协议（MCP）的天气服务，提供各种气象数据查询功能，如天气预报、气象预警、太阳辐射等。

功能

• 天气预报获取未来三天的详细天气预报
• 气象预警查询实时的气象灾害预警信息
• 生活指数获取各种生活指数预测，如洗车、穿衣、感冒等
• 空气质量获取城市的空气质量指数（AQI）和主要污染物信息
• 逐时预报获取未来24/72/168小时的逐时天气数据，包括温度、天气状况、风速/方向、相对湿度、气压、降水概率、露点、云量等
• 实时天气获取接近实时的天气（温度、体感温度、风、湿度、气压、降水、能见度、露点、云量等）
• 安全认证使用JWT+EdDSA数字签名认证
• 详细日志完整的操作日志和错误处理

安装

uv tool install hefeng-weather-mcp

或者使用pip安装：

pip install hefeng-weather-mcp

HEFENG_API_HOST=devapi.qweather.com
HEFENG_PROJECT_ID=你的项目ID
HEFENG_KEY_ID=你的凭据ID
HEFENG_PRIVATE_KEY_PATH=./ed25519-private.pem

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

使用

流式HTTP模式

配置环境变量后运行程序

hefeng-weather-mcp http

VSCode MCP配置文件：

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

STDio模式

安装并配置环境变量后运行程序

hefeng-weather-mcp stdio

VSCode MCP配置文件：

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

或使用uv命令：

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

预备条件

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

开发

1. 克隆项目

git clone https://github.com/yeisme/hefeng-weather-mcp.git
cd hefeng-weather-mcp

2. 安装依赖

使用Pip：

pip install -e .

或使用UV（推荐）：

uv sync

3. 创建和风天气项目

1. 访问和风天气控制台
2. 注册/登录账户
3. 点击“创建项目”并填写项目信息
4. 记录生成的项目ID

4. 生成密钥对

在项目的根目录下运行以下命令以生成EdDSA ed25519密钥对：

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

这将生成两个文件：

• ed25519-private.pem私钥文件（保密，不要提交到代码仓库）
• ed25519-public.pem公钥文件

5. 创建API凭证

1. 在和风天气控制台中进入已创建的项目
2. 点击“凭证管理”→“创建凭证”
3. 选择凭证类型为数字签名
4. 上传刚刚生成的ed25519-public.pem公钥文件
5. 记录生成的凭证ID

6. 配置环境变量

复制配置模板文件：

cp .env.example .env

编辑.env文件，填写实际配置信息：

# 和风天气API配置
HEFENG_API_HOST=devapi.qweather.com
HEFENG_PROJECT_ID=你的项目ID
HEFENG_KEY_ID=你的凭据ID
HEFENG_PRIVATE_KEY_PATH=./ed25519-private.pem

配置说明：

• HEFENG_API_HOST：
  • 开发环境使用：devapi.qweather.com
  • 生产环境使用：api.qweather.com
• HEFENG_PROJECT_ID步骤3中获得的项目ID
• HEFENG_KEY_ID步骤5中获得的凭证ID
• HEFENG_PRIVATE_KEY_PATH：私钥文件路径，默认为./ed25519-private.pem

开发指南

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

许可证

MIT许可证

贡献指南

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

提交问题

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

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

相关链接

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

联系方式

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

• 📧 电子邮件：yefun2004@gmail.com
• 🐛 问题：GitHub Issues
• 💬 讨论：GitHub Discussions

---

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