Python MCP Server

Python MCP Server Collection

一组基于 FastMCP 构建的 Model Context Protocol (MCP) 服务器实现，提供二维码生成和天气预报等实用功能。

📋 目录

• 项目简介
• 功能特性
• 项目结构
• 环境要求
• 安装配置
• 使用说明
• API 文档
• 环境变量
• 技术栈

---

项目简介

本项目实现了两个独立的 MCP Server：

1. QR Code Server (qrcode_server.py) - 二维码生成服务，支持可视化预览
2. QWeather Server (q_weather.py) - 和风天气 API 封装，提供实时天气、预报、预警等服务

功能特性

QR Code Server

• ✅ 文本/链接转二维码
• ✅ Base64 编码输出
• ✅ 内置交互式 UI 预览界面
• ✅ Streamable HTTP 传输协议

QWeather Server

• ✅ 实时天气查询
• ✅ 3 天天气预报
• ✅ 168 小时逐小时预报
• ✅ 生活指数预报
• ✅ 天气预警信息
• ✅ 热门城市列表
• ✅ JWT 自动认证（EdDSA 算法）
• ✅ 自定义路由聚合接口

项目结构

python-mcp-server/
├── qrcode_server.py      # 二维码生成 MCP Server
├── q_weather.py          # 和风天气 MCP Server
├── requirements.txt      # Python 依赖
├── .env                  # 环境变量配置（需自行创建）
└── .env.example          # 环境变量示例

环境要求

• Python 3.10+
• pip / uv 包管理器

安装配置

1. 克隆项目

git clone <repo-url>
cd python-mcp-server

2. 安装依赖

# 使用 pip
pip install -r requirements.txt

# 或使用 uv（推荐）
uv pip install -r requirements.txt

3. 配置环境变量

复制示例文件并填写配置：

cp .env.example .env

编辑 .env 文件，至少需要配置以下项（根据使用的服务）：

QR Code Server（无需额外配置）

QWeather Server

QWEATHER_API_HOST=devapi.qweather.com
QWEATHER_KEY_ID=your_key_id
QWEATHER_PROJECT_ID=your_project_id

获取和风天气密钥: 访问 和风天气开发者平台 注册获取

使用说明

启动 QR Code Server

python qrcode_server.py

服务将在 http://0.0.0.0:8080 启动。

启动 QWeather Server

python q_weather.py

服务将在 http://0.0.0.0:8080 启动。

与 AI 助手集成

将 MCP Server 配置到你的 AI 客户端（如 Claude Desktop、Zed 等）：

{
  "mcpServers": {
    "qrcode": {
      "command": "python",
      "args": ["qrcode_server.py"],
      "transport": "streamable-http"
    },
    "qweather": {
      "command": "python",
      "args": ["q_weather.py"],
      "transport": "streamable-http"
    }
  }
}

API 文档

QR Code Server

Tool	参数	描述
generate_qr	text: str	生成指定文本的二维码

示例：

generate_qr(text="https://www.example.com")

返回 Base64 编码的 PNG 图片，可在支持的客户端中直接预览。

---

QWeather Server

Tool	参数	描述
get_real_tool	location: str	获取实时天气
get_day_tool	location: str	获取 3 天预报
get_hour_tool	location: str	获取 168 小时逐小时预报
indices_days_tool	location: str	获取 3 天生活指数
weatheralert_current_tool	location: str	获取当前天气预警
prompt	location: str	生成天气提示词

Resource	描述
resource://city-top	热门城市列表

Custom Route	方法	描述
/all	GET	聚合所有天气数据（?location=北京）

示例：

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

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

HTTP 接口示例：

curl "http://localhost:8080/all?location=广州"

环境变量

变量名	必填	描述
QWEATHER_API_HOST	是	和风天气 API 主机
QWEATHER_KEY_ID	是	和风天气密钥 ID
QWEATHER_PROJECT_ID	是	和风天气项目 ID
QWEATHER_PRIVATE_KEY	否	私钥（代码中已内置示例）
FASTMCP_LOG_LEVEL	否	日志级别
FASTMCP_MASK_ERROR_DETAILS	否	是否隐藏错误详情

技术栈

• FastMCP - 轻量级 MCP Server 框架
• PyJWT - JWT 令牌生成（EdDSA 签名）
• Requests - HTTP 客户端
• Python-dotenv - 环境变量管理
• Qrcode - 二维码生成库
• FastAPI - Web 框架（底层）

许可证

MIT License

---