qweather-mcp

天气查询 API

这是一个基于FastAPI开发的天气查询API服务，同时支持MCP（Machine Callable Program）接口，可以被AI助手直接调用。

使用

{
  "mcpServers": {
    "qweather": {
      "command": "uvx",
      "args": [
        "qweather-mcp"
      ],
      "env": {
        "WEATHER_PRIVATE_KEY": "YOUR_PRIVATE_KEY",
        "WEATHER_PROJECT_ID": "YOUR_PROJECT_ID",
        "WEATHER_KEY_ID": "YOUR_KEY_ID",
        "WEATHER_API_HOST": "YOUR_URL_ADDRESS.qweatherapi.com",
        "WEATHER_BEARER_TOKEN": ""
      }
    }
  }
}

功能特点

• 支持通过城市名称查询天气信息
• 提供JWT令牌生成和验证
• 实现了MCP接口，可被AI助手直接调用
• 使用和风天气API作为数据源
• 支持Bearer Token认证

接口说明

主要接口

• / - API主页，提供接口概览
• /generate-jwt - 生成JWT令牌
• /city/lookup - 根据城市名称查询位置ID
• /weather/now - 根据位置ID查询当前天气
• /weather/by-city - 一站式查询城市天气（只需提供城市名）

MCP接口

本服务实现了MCP接口规范，可以被支持MCP的AI助手直接调用，目前开放的操作为：

• get_weather_by_city - 通过城市名称查询天气

安装与运行

环境要求

Python 3.8+

安装依赖

pip install -r requirements.txt

运行服务

uvicorn main:app --reload

服务将在 http://localhost:8000 启动，API文档可访问 http://localhost:8000/docs

配置说明

项目使用环境变量或.env文件进行配置。主要配置项包括：

API配置

• WEATHER_PRIVATE_KEY - EdDSA私钥，用于JWT签名
• WEATHER_PROJECT_ID - 项目ID，用于JWT的subject声明
• WEATHER_KEY_ID - 密钥ID，用于JWT的kid头部
• WEATHER_API_HOST - 和风天气API主机地址

安全配置

• WEATHER_BEARER_TOKEN - API访问令牌

服务器配置

• HOST - 服务器监听地址，默认为0.0.0.0
• PORT - 服务器端口，默认为8000
• DEBUG - 是否启用调试模式，默认为True

JWT配置

• JWT_DEFAULT_EXPIRY - JWT令牌默认过期时间（秒），默认为900（15分钟）

缓存配置

• TOKEN_CACHE_ENABLED - 是否启用令牌缓存，默认为True

配置方法

• 创建.env文件（参考项目中的.env.example）
• 设置所需的环境变量

# 复制示例配置文件
cp .env.example .env

# 编辑配置文件
vim .env

使用示例

查询城市天气

curl -X POST "http://localhost:8000/weather/by-city" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer zishu.co" \
     -d '{"city":"北京"}'

生成JWT令牌

curl -X POST "http://localhost:8000/generate-jwt" \
     -H "Content-Type: application/json" \
     -d '{"expiry_seconds": 3600}'

错误处理

API使用标准HTTP状态码表示请求结果：

• 200: 请求成功
• 401: 认证失败
• 404: 资源不存在（如找不到指定城市）
• 500: 服务器内部错误

许可证

MIT