# 和风天气 MCP 服务
一个基于 Model Context Protocol (MCP) 的和风天气服务，提供天气预报、气象预警、太阳辐射等多种气象数据查询功能。
## 功能特性
- 🌤️ **天气预报**: 获取未来三天详细天气预报
- ⚠️ **气象预警**: 查询实时气象灾害预警信息
- ☀️ **太阳辐射**: 获取逐小时太阳辐射预报数据
- 🔐 **安全认证**: 使用 JWT + EdDSA 数字签名认证
- 📝 **详细日志**: 完整的操作日志和错误处理
## 安装
```bash
uv tool install hefeng-weather-mcp
```
或使用 pip 安装：
```bash
pip install hefeng-weather-mcp
```
```env
HEFENG_API_HOST=devapi.qweather.com
HEFENG_PROJECT_ID=你的项目ID
HEFENG_KEY_ID=你的凭据ID
HEFENG_PRIVATE_KEY_PATH=./ed25519-private.pem
```
## 使用
### streamable-http 模式
配置环境变量后运行程序
```bash
hefeng-weather-mcp http
```
vscode MCP 配置文件：
```json
{
"servers": {
"hefeng-weather-mcp": {
"url": "http://127.0.0.1:8000/mcp",
"type": "http"
}
},
"inputs": []
}
```
### stdio 模式
安装并配置环境变量后运行程序
```bash
hefeng-weather-mcp stdio
```
vscode MCP 配置文件：
```json
{
"servers": {
"hefeng-weather-mcp-stdio": {
"type": "stdio",
"command": "hefeng-weather-mcp stdio"
}
},
"inputs": []
}
```
或者使用 `uv` 命令：
```json
{
"servers": {
"hefeng-weather-mcp-uv": {
"type": "stdio",
"command": "uvx hefeng-weather-mcp stdio",
"envFile": "${workspaceFolder}/.env"
}
},
"inputs": []
}
```
## 前置要求
- Python >= 3.11
- OpenSSL (用于生成密钥对)
- 和风天气开发者账号
## 开发
### 1. 克隆项目
```bash
git clone https://github.com/yeisme/hefeng-weather-mcp.git
cd hefeng-weather-mcp
```
### 2. 安装依赖
使用 pip:
```bash
pip install -e .
```
或使用 uv (推荐):
```bash
uv sync
```
### 3. 创建和风天气项目
1. 访问 [和风天气控制台](https://console.qweather.com/project/)
2. 注册/登录账号
3. 点击"创建项目"，填写项目信息
4. 记录下生成的 **Project ID**
### 4. 生成密钥对
在项目根目录下运行以下命令生成 EdDSA ed25519 密钥对：
```bash
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. 记录下生成的 **Key ID**
### 6. 配置环境变量
复制配置模板文件：
```bash
cp .env.example .env
```
编辑 `.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 License
## 贡献指南
我们欢迎任何形式的贡献！
### 提交 Issue
如果你发现了 bug 或有功能建议，请：
1. 查看现有的 Issue，避免重复提交
2. 使用清晰的标题和详细的描述
3. 如果是 bug 报告，请包含重现步骤和环境信息
## 相关链接
- [和风天气官网](https://www.qweather.com/)
- [和风天气开发者控制台](https://console.qweather.com/project/)
- [和风天气 API 文档](https://dev.qweather.com/docs/api/)
- [Model Context Protocol](https://modelcontextprotocol.io/)
## 联系方式
如有问题或建议，请通过以下方式联系：
- 📧 Email: [yefun2004@gmail.com](mailto:yefun2004@gmail.com)
- 🐛 Issues: [GitHub Issues](https://github.com/yeisme/hefeng-weather-mcp/issues)
- 💬 讨论: [GitHub Discussions](https://github.com/yeisme/hefeng-weather-mcp/discussions)
---
**免责声明**: 本项目仅供学习和研究使用，请遵守和风天气的服务条款和 API 使用规范。
Raw data
{
"_id": null,
"home_page": null,
"name": "hefeng-weather-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "weather, mcp, hefeng, qweather, climate",
"author": null,
"author_email": "yeisme <yefun2004@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/af/cc/e79a4b6f61ca87eeb02fe1b16b81402a8d360a64fee9f869bbea99acee4c/hefeng_weather_mcp-0.1.3.tar.gz",
"platform": null,
"description": "# \u548c\u98ce\u5929\u6c14 MCP \u670d\u52a1\r\n\r\n\u4e00\u4e2a\u57fa\u4e8e Model Context Protocol (MCP) \u7684\u548c\u98ce\u5929\u6c14\u670d\u52a1\uff0c\u63d0\u4f9b\u5929\u6c14\u9884\u62a5\u3001\u6c14\u8c61\u9884\u8b66\u3001\u592a\u9633\u8f90\u5c04\u7b49\u591a\u79cd\u6c14\u8c61\u6570\u636e\u67e5\u8be2\u529f\u80fd\u3002\r\n\r\n## \u529f\u80fd\u7279\u6027\r\n\r\n- \ud83c\udf24\ufe0f **\u5929\u6c14\u9884\u62a5**: \u83b7\u53d6\u672a\u6765\u4e09\u5929\u8be6\u7ec6\u5929\u6c14\u9884\u62a5\r\n- \u26a0\ufe0f **\u6c14\u8c61\u9884\u8b66**: \u67e5\u8be2\u5b9e\u65f6\u6c14\u8c61\u707e\u5bb3\u9884\u8b66\u4fe1\u606f\r\n- \u2600\ufe0f **\u592a\u9633\u8f90\u5c04**: \u83b7\u53d6\u9010\u5c0f\u65f6\u592a\u9633\u8f90\u5c04\u9884\u62a5\u6570\u636e\r\n- \ud83d\udd10 **\u5b89\u5168\u8ba4\u8bc1**: \u4f7f\u7528 JWT + EdDSA \u6570\u5b57\u7b7e\u540d\u8ba4\u8bc1\r\n- \ud83d\udcdd **\u8be6\u7ec6\u65e5\u5fd7**: \u5b8c\u6574\u7684\u64cd\u4f5c\u65e5\u5fd7\u548c\u9519\u8bef\u5904\u7406\r\n\r\n## \u5b89\u88c5\r\n\r\n```bash\r\nuv tool install hefeng-weather-mcp\r\n```\r\n\r\n\u6216\u4f7f\u7528 pip \u5b89\u88c5\uff1a\r\n\r\n```bash\r\npip install hefeng-weather-mcp\r\n```\r\n\r\n```env\r\nHEFENG_API_HOST=devapi.qweather.com\r\nHEFENG_PROJECT_ID=\u4f60\u7684\u9879\u76eeID\r\nHEFENG_KEY_ID=\u4f60\u7684\u51ed\u636eID\r\nHEFENG_PRIVATE_KEY_PATH=./ed25519-private.pem\r\n```\r\n\r\n## \u4f7f\u7528\r\n\r\n### streamable-http \u6a21\u5f0f\r\n\r\n\u914d\u7f6e\u73af\u5883\u53d8\u91cf\u540e\u8fd0\u884c\u7a0b\u5e8f\r\n\r\n```bash\r\nhefeng-weather-mcp http\r\n```\r\n\r\nvscode MCP \u914d\u7f6e\u6587\u4ef6\uff1a\r\n\r\n```json\r\n{\r\n \"servers\": {\r\n \"hefeng-weather-mcp\": {\r\n \"url\": \"http://127.0.0.1:8000/mcp\",\r\n \"type\": \"http\"\r\n }\r\n },\r\n \"inputs\": []\r\n}\r\n```\r\n\r\n### stdio \u6a21\u5f0f\r\n\r\n\u5b89\u88c5\u5e76\u914d\u7f6e\u73af\u5883\u53d8\u91cf\u540e\u8fd0\u884c\u7a0b\u5e8f\r\n\r\n```bash\r\nhefeng-weather-mcp stdio\r\n```\r\n\r\nvscode MCP \u914d\u7f6e\u6587\u4ef6\uff1a\r\n\r\n```json\r\n{\r\n \"servers\": {\r\n \"hefeng-weather-mcp-stdio\": {\r\n \"type\": \"stdio\",\r\n \"command\": \"hefeng-weather-mcp stdio\"\r\n }\r\n },\r\n \"inputs\": []\r\n}\r\n```\r\n\r\n\u6216\u8005\u4f7f\u7528 `uv` \u547d\u4ee4\uff1a\r\n\r\n```json\r\n{\r\n \"servers\": {\r\n \"hefeng-weather-mcp-uv\": {\r\n \"type\": \"stdio\",\r\n \"command\": \"uvx hefeng-weather-mcp stdio\",\r\n \"envFile\": \"${workspaceFolder}/.env\"\r\n }\r\n },\r\n \"inputs\": []\r\n}\r\n```\r\n\r\n## \u524d\u7f6e\u8981\u6c42\r\n\r\n- Python >= 3.11\r\n- OpenSSL (\u7528\u4e8e\u751f\u6210\u5bc6\u94a5\u5bf9)\r\n- \u548c\u98ce\u5929\u6c14\u5f00\u53d1\u8005\u8d26\u53f7\r\n\r\n## \u5f00\u53d1\r\n\r\n### 1. \u514b\u9686\u9879\u76ee\r\n\r\n```bash\r\ngit clone https://github.com/yeisme/hefeng-weather-mcp.git\r\ncd hefeng-weather-mcp\r\n```\r\n\r\n### 2. \u5b89\u88c5\u4f9d\u8d56\r\n\r\n\u4f7f\u7528 pip:\r\n\r\n```bash\r\npip install -e .\r\n```\r\n\r\n\u6216\u4f7f\u7528 uv (\u63a8\u8350):\r\n\r\n```bash\r\nuv sync\r\n```\r\n\r\n### 3. \u521b\u5efa\u548c\u98ce\u5929\u6c14\u9879\u76ee\r\n\r\n1. \u8bbf\u95ee [\u548c\u98ce\u5929\u6c14\u63a7\u5236\u53f0](https://console.qweather.com/project/)\r\n2. \u6ce8\u518c/\u767b\u5f55\u8d26\u53f7\r\n3. \u70b9\u51fb\"\u521b\u5efa\u9879\u76ee\"\uff0c\u586b\u5199\u9879\u76ee\u4fe1\u606f\r\n4. \u8bb0\u5f55\u4e0b\u751f\u6210\u7684 **Project ID**\r\n\r\n### 4. \u751f\u6210\u5bc6\u94a5\u5bf9\r\n\r\n\u5728\u9879\u76ee\u6839\u76ee\u5f55\u4e0b\u8fd0\u884c\u4ee5\u4e0b\u547d\u4ee4\u751f\u6210 EdDSA ed25519 \u5bc6\u94a5\u5bf9\uff1a\r\n\r\n```bash\r\nopenssl genpkey -algorithm ED25519 -out ed25519-private.pem \\\r\n&& openssl pkey -pubout -in ed25519-private.pem > ed25519-public.pem\r\n```\r\n\r\n\u8fd9\u5c06\u751f\u6210\u4e24\u4e2a\u6587\u4ef6\uff1a\r\n\r\n- `ed25519-private.pem`: \u79c1\u94a5\u6587\u4ef6\uff08\u4fdd\u5bc6\uff0c\u4e0d\u8981\u63d0\u4ea4\u5230\u4ee3\u7801\u5e93\uff09\r\n- `ed25519-public.pem`: \u516c\u94a5\u6587\u4ef6\r\n\r\n### 5. \u521b\u5efa API \u51ed\u636e\r\n\r\n1. \u5728\u548c\u98ce\u5929\u6c14\u63a7\u5236\u53f0\u4e2d\uff0c\u8fdb\u5165\u4f60\u521b\u5efa\u7684\u9879\u76ee\r\n2. \u70b9\u51fb\"\u51ed\u636e\u7ba1\u7406\" \u2192 \"\u521b\u5efa\u51ed\u636e\"\r\n3. \u9009\u62e9\u51ed\u636e\u7c7b\u578b\u4e3a **\"\u6570\u5b57\u7b7e\u540d\"**\r\n4. \u4e0a\u4f20\u521a\u624d\u751f\u6210\u7684 `ed25519-public.pem` \u516c\u94a5\u6587\u4ef6\r\n5. \u8bb0\u5f55\u4e0b\u751f\u6210\u7684 **Key ID**\r\n\r\n### 6. \u914d\u7f6e\u73af\u5883\u53d8\u91cf\r\n\r\n\u590d\u5236\u914d\u7f6e\u6a21\u677f\u6587\u4ef6\uff1a\r\n\r\n```bash\r\ncp .env.example .env\r\n```\r\n\r\n\u7f16\u8f91 `.env` \u6587\u4ef6\uff0c\u586b\u5165\u5b9e\u9645\u7684\u914d\u7f6e\u4fe1\u606f\uff1a\r\n\r\n```env\r\n# \u548c\u98ce\u5929\u6c14API\u914d\u7f6e\r\nHEFENG_API_HOST=devapi.qweather.com\r\nHEFENG_PROJECT_ID=\u4f60\u7684\u9879\u76eeID\r\nHEFENG_KEY_ID=\u4f60\u7684\u51ed\u636eID\r\nHEFENG_PRIVATE_KEY_PATH=./ed25519-private.pem\r\n```\r\n\r\n**\u914d\u7f6e\u8bf4\u660e\uff1a**\r\n\r\n- `HEFENG_API_HOST`:\r\n - \u5f00\u53d1\u73af\u5883\u4f7f\u7528: `devapi.qweather.com`\r\n - \u751f\u4ea7\u73af\u5883\u4f7f\u7528: `api.qweather.com`\r\n- `HEFENG_PROJECT_ID`: \u6b65\u9aa4 3 \u4e2d\u83b7\u5f97\u7684\u9879\u76ee ID\r\n- `HEFENG_KEY_ID`: \u6b65\u9aa4 5 \u4e2d\u83b7\u5f97\u7684\u51ed\u636e ID\r\n- `HEFENG_PRIVATE_KEY_PATH`: \u79c1\u94a5\u6587\u4ef6\u8def\u5f84\uff0c\u9ed8\u8ba4\u4e3a `./ed25519-private.pem`\r\n\r\n### \u5f00\u53d1\u6307\u5357\r\n\r\n1. **\u4ee3\u7801\u98ce\u683c**: \u9879\u76ee\u4f7f\u7528 `ruff` \u8fdb\u884c\u4ee3\u7801\u683c\u5f0f\u5316\u548c\u68c0\u67e5\r\n2. **\u7c7b\u578b\u68c0\u67e5**: \u4f7f\u7528 `mypy` \u8fdb\u884c\u9759\u6001\u7c7b\u578b\u68c0\u67e5\r\n3. **\u6d4b\u8bd5**: \u5efa\u8bae\u4e3a\u65b0\u529f\u80fd\u6dfb\u52a0\u76f8\u5e94\u7684\u5355\u5143\u6d4b\u8bd5\r\n4. **\u6587\u6863**: \u786e\u4fdd\u6240\u6709\u65b0\u529f\u80fd\u90fd\u6709\u8be6\u7ec6\u7684 docstring \u6587\u6863\r\n\r\n## \u8bb8\u53ef\u8bc1\r\n\r\nMIT License\r\n\r\n## \u8d21\u732e\u6307\u5357\r\n\r\n\u6211\u4eec\u6b22\u8fce\u4efb\u4f55\u5f62\u5f0f\u7684\u8d21\u732e\uff01\r\n\r\n### \u63d0\u4ea4 Issue\r\n\r\n\u5982\u679c\u4f60\u53d1\u73b0\u4e86 bug \u6216\u6709\u529f\u80fd\u5efa\u8bae\uff0c\u8bf7\uff1a\r\n\r\n1. \u67e5\u770b\u73b0\u6709\u7684 Issue\uff0c\u907f\u514d\u91cd\u590d\u63d0\u4ea4\r\n2. \u4f7f\u7528\u6e05\u6670\u7684\u6807\u9898\u548c\u8be6\u7ec6\u7684\u63cf\u8ff0\r\n3. \u5982\u679c\u662f bug \u62a5\u544a\uff0c\u8bf7\u5305\u542b\u91cd\u73b0\u6b65\u9aa4\u548c\u73af\u5883\u4fe1\u606f\r\n\r\n## \u76f8\u5173\u94fe\u63a5\r\n\r\n- [\u548c\u98ce\u5929\u6c14\u5b98\u7f51](https://www.qweather.com/)\r\n- [\u548c\u98ce\u5929\u6c14\u5f00\u53d1\u8005\u63a7\u5236\u53f0](https://console.qweather.com/project/)\r\n- [\u548c\u98ce\u5929\u6c14 API \u6587\u6863](https://dev.qweather.com/docs/api/)\r\n- [Model Context Protocol](https://modelcontextprotocol.io/)\r\n\r\n## \u8054\u7cfb\u65b9\u5f0f\r\n\r\n\u5982\u6709\u95ee\u9898\u6216\u5efa\u8bae\uff0c\u8bf7\u901a\u8fc7\u4ee5\u4e0b\u65b9\u5f0f\u8054\u7cfb\uff1a\r\n\r\n- \ud83d\udce7 Email: [yefun2004@gmail.com](mailto:yefun2004@gmail.com)\r\n- \ud83d\udc1b Issues: [GitHub Issues](https://github.com/yeisme/hefeng-weather-mcp/issues)\r\n- \ud83d\udcac \u8ba8\u8bba: [GitHub Discussions](https://github.com/yeisme/hefeng-weather-mcp/discussions)\r\n\r\n---\r\n\r\n**\u514d\u8d23\u58f0\u660e**: \u672c\u9879\u76ee\u4ec5\u4f9b\u5b66\u4e60\u548c\u7814\u7a76\u4f7f\u7528\uff0c\u8bf7\u9075\u5b88\u548c\u98ce\u5929\u6c14\u7684\u670d\u52a1\u6761\u6b3e\u548c API \u4f7f\u7528\u89c4\u8303\u3002\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "\u548c\u98ce\u5929\u6c14 MCP \u670d\u52a1 - \u57fa\u4e8e Model Context Protocol \u7684\u5929\u6c14\u6570\u636e\u67e5\u8be2\u670d\u52a1",
"version": "0.1.3",
"project_urls": {
"Documentation": "https://github.com/yeisme/hefeng-weather-mcp#readme",
"Homepage": "https://github.com/yeisme/hefeng-weather-mcp",
"Issues": "https://github.com/yeisme/hefeng-weather-mcp/issues",
"Repository": "https://github.com/yeisme/hefeng-weather-mcp.git"
},
"split_keywords": [
"weather",
" mcp",
" hefeng",
" qweather",
" climate"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "337d438b00ea26f36299d1a9efee4fd96f998a76581e908540c7e951ddb17cba",
"md5": "af4b720e0c56c9781de1380cd14e4233",
"sha256": "0ddb594c8ad2f8156b6b331f97b074361a0227874f0e61b1e987c421ac1f40aa"
},
"downloads": -1,
"filename": "hefeng_weather_mcp-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "af4b720e0c56c9781de1380cd14e4233",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 8126,
"upload_time": "2025-07-21T01:58:44",
"upload_time_iso_8601": "2025-07-21T01:58:44.862076Z",
"url": "https://files.pythonhosted.org/packages/33/7d/438b00ea26f36299d1a9efee4fd96f998a76581e908540c7e951ddb17cba/hefeng_weather_mcp-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "afcce79a4b6f61ca87eeb02fe1b16b81402a8d360a64fee9f869bbea99acee4c",
"md5": "f0fdbffacc42e10db2809fe65d16496a",
"sha256": "2241eeb465b598f883e87db497e1eec7239d11cfa60b93386bdf19006c5eab2d"
},
"downloads": -1,
"filename": "hefeng_weather_mcp-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "f0fdbffacc42e10db2809fe65d16496a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 9758,
"upload_time": "2025-07-21T01:58:46",
"upload_time_iso_8601": "2025-07-21T01:58:46.207809Z",
"url": "https://files.pythonhosted.org/packages/af/cc/e79a4b6f61ca87eeb02fe1b16b81402a8d360a64fee9f869bbea99acee4c/hefeng_weather_mcp-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-21 01:58:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yeisme",
"github_project": "hefeng-weather-mcp#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "hefeng-weather-mcp"
}
JSON
