QWeather MCP Server

基于 FastMCP 框架构建的和风天气（QWeather）Model Context Protocol 服务器，为 AI 助手和大型语言模型提供标准化的天气数据查询能力。

---

📋 目录

• 项目简介
• 核心功能
• 技术架构
• 快速开始
• API 参考
• 配置说明
• 使用示例
• 技术细节

---

项目简介

本项目是一个轻量级、生产级的天气数据服务，通过 MCP（Model Context Protocol）协议将和风天气 API 暴露给 AI 应用。支持实时天气、多日预报、小时级预报、生活指数和天气预警等多种数据查询。

特性亮点

• ✅ MCP 协议兼容 - 与 Claude Desktop、IDE 插件等 MCP 客户端无缝集成
• ✅ Streamable HTTP 传输 - 基于 SSE 的流式传输协议
• ✅ JWT 自动认证 - 使用 EdDSA 算法自动生成 QWeather API 令牌
• ✅ 城市地理编码 - 自动将城市名称转换为位置 ID 和坐标
• ✅ 结构化日志 - 完整的日志记录，便于调试和监控
• ✅ 文件上传支持 - 集成 FileUpload 提供者
• ✅ 生成式 UI - 集成 GenerativeUI 提供者

---

核心功能

天气工具（MCP Tools）

工具名称	功能描述	QWeather API
get_real_tool	获取实时天气	/v7/weather/now
get_day_tool	获取 3 天天气预报	/v7/weather/3d
get_hour_tool	获取 168 小时预报	/v7/weather/168h
indices_days_tool	获取生活指数预报	/v7/indices/3d
weatheralert_current_tool	获取生效中的天气预警	/weatheralert/v1/current

资源（Resources）

资源 URI	描述
resource://city-top	热门城市列表（中国 Top 20）

提示词（Prompts）

提示词	描述
prompt(location)	生成指定位置的天气查询提示词

自定义 HTTP 端点

端点	方法	描述
/all?location={城市名}	GET	一次性获取全部天气数据（实时 +3 天 +168 小时 + 预警）

---

技术架构

┌─────────────────────────────────────────────────────────────┐
│                     MCP Client (AI Agent)                    │
│              (Claude Desktop / IDE Plugin / Custom)          │
└────────────────────────────┬────────────────────────────────┘
                             │ MCP Protocol (SSE)
                             ▼
┌─────────────────────────────────────────────────────────────┐
│                   QWeather MCP Server                        │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐   │
│  │  MCP Tools   │  │  Resources   │  │  Custom Routes   │   │
│  │  (5 tools)   │  │  (city-top)  │  │  (/all endpoint) │   │
│  └──────────────┘  └──────────────┘  └──────────────────┘   │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐   │
│  │  JWT Auth    │  │  City Lookup │  │  Structured Log  │   │
│  │  (EdDSA)     │  │  (Geocoding) │  │  (Timestamped)   │   │
│  └──────────────┘  └──────────────┘  └──────────────────┘   │
└────────────────────────────┬────────────────────────────────┘
                             │ HTTPS REST API
                             ▼
┌─────────────────────────────────────────────────────────────┐
│                  QWeather API Server                         │
│         (和风天气开放平台 - pc7by6rwxe.re.qweatherapi.com)    │
└─────────────────────────────────────────────────────────────┘

---

快速开始

环境要求

• Python 3.10+
• 和风天气 API 密钥（申请地址）

安装依赖

pip install -r requirements.txt

配置环境变量

创建 .env 文件并填入 QWeather API 凭证：

# QWeather API 配置
QWEATHER_API_HOST=pc7by6rwxe.re.qweatherapi.com
QWEATHER_KEY_ID=K4WMKAU7WN
QWEATHER_PROJECT_ID=45KWWPU7K5
QWEATHER_PRIVATE_KEY=969743e5dc0f4b2fa037d6206de47505

注意：QWEATHER_PRIVATE_KEY 为 Ed25519 私钥，请妥善保管。

启动服务器

python q_weather.py

服务器将在 http://0.0.0.0:8080 启动，使用 streamable-http 传输协议。

---

API 参考

MCP 工具调用

通过 MCP 客户端调用工具：

# 实时天气
get_real_tool(location="北京")

# 3 天预报
get_day_tool(location="上海")

# 168 小时预报
get_hour_tool(location="广州")

# 生活指数
indices_days_tool(location="深圳")

# 天气预警
weatheralert_current_tool(location="成都")

HTTP 端点调用

# 获取全部天气数据
curl "http://localhost:8080/all?location=北京"

响应示例：

{
  "real": "{\"code\":\"200\",\"now\":{\"temp\":\"25\",\"icon\":\"1\",\"text\":\"晴\",\"feelsLike\":\"27\"}}",
  "day": "{\"code\":\"200\",\"daily\":[...]}\"",
  "hour": "{\"code\":\"200\",\"hourly\":[...]}\"",
  "alert": "{\"code\":\"200\",\"alert\":[]}"
}

资源访问

resource://city-top

返回中国热门城市列表（Top 20）。

---

配置说明

环境变量

变量名	描述	示例
QWEATHER_API_HOST	QWeather API 主机地址	pc7by6rwxe.re.qweatherapi.com
QWEATHER_KEY_ID	API Key ID	K4WMKAU7WN
QWEATHER_PROJECT_ID	项目 ID	45KWWPU7K5
QWEATHER_PRIVATE_KEY	Ed25519 私钥	969743e5...

服务器配置

修改 q_weather.py 中的启动参数：

if __name__ == "__main__":
    mcp.run(
        transport="streamable-http",  # 传输协议
        host="0.0.0.0",               # 监听地址
        port=8080                     # 监听端口
    )

---

使用示例

集成到 Claude Desktop

在 claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "qweather": {
      "command": "python",
      "args": ["q_weather.py"],
      "cwd": "/path/to/python-mcp-server"
    }
  }
}

自然语言查询

启动后，AI 助手可以自然语言查询天气：

用户：北京今天天气怎么样？
AI: 让我查询一下北京的实时天气...
    (调用 get_real_tool("北京"))
    北京当前气温 25°C，天气晴朗，体感温度 27°C。

---

技术细节

JWT 认证机制

服务器使用 EdDSA（Ed25519）算法生成 JWT 令牌：

def generate_jwt() -> str:
    payload = {
        "iat": int(time.time()) - 30,    # 签发时间（-30 秒容差）
        "exp": int(time.time()) + 900,   # 过期时间（15 分钟）
        "sub": QWEATHER_PROJECT_ID,      # 项目 ID
    }
    headers = {"kid": QWEATHER_KEY_ID}   # 密钥 ID
    return jwt.encode(payload, QWEATHER_PRIVATE_KEY, algorithm="EdDSA", headers=headers)

城市地理编码

自动将城市名称转换为 QWeather 位置 ID：

def city_lookup(location: str) -> str:
    # GET /geo/v2/city/lookup?location=北京&range=cn&number=1
    # 返回：{"location": [{"id": "101010100", "name": "北京", ...}]}

日志格式

%H:%M:%S - LEVEL -[filename:lineno]- name - message

示例：

14:30:45 - INFO -[q_weather.py:63]- __main__ - {'location': '北京', 'range': 'cn', 'number': 1}

---

项目结构

python-mcp-server/
├── q_weather.py          # 主服务器实现（~290 行）
├── requirements.txt      # Python 依赖
├── .env                  # 环境变量配置（需自行创建）
└── README.md             # 项目文档

---

依赖说明

核心依赖

包名	用途
fastmcp	MCP 服务器框架
python-dotenv	环境变量加载
PyJWT + cryptography	JWT 令牌生成
requests	HTTP 客户端
fastapi	HTTP 响应处理

完整依赖列表

详见 requirements.txt，包含 FastMCP 扩展功能所需的其他包。

---

常见问题

Q: 如何获取 QWeather API 密钥？

A: 访问 和风天气开放平台 注册账号并创建应用。

Q: 服务器启动失败怎么办？

A: 检查以下几点：

1. 确认 .env 文件存在且配置正确
2. 确认端口 8080 未被占用
3. 检查网络连接是否可达 QWeather API

Q: 如何添加新的天气工具？

A: 使用 @mcp.tool 装饰器定义新函数：

@mcp.tool
def new_weather_tool(location: str) -> str:
    """工具描述"""
    token = generate_jwt()
    # 调用 QWeather API
    return json.dumps(result)

---

许可证

MIT License

---

相关链接

• FastMCP 官方文档
• QWeather API 文档
• Model Context Protocol

---

QWeather MCP Server — 为 AI 赋能的天气数据服务

Made with ❤️ using FastMCP