QQZone MCP Server

把 QQ 空间数据接口封装为 MCP 工具，支持 扫码登录、Web 控制台、SSE 远程接入。基于开源 QzoneExporter 验证过的接口参数重写，仅依赖 mcp + requests（Web 模式额外需要 fastapi + uvicorn）。

功能特性

• 8 个查询工具：说说（分页/搜索）、资料卡、相册、留言板、空间统计

• 扫码登录：WebUI 一键拉起 QQ 官方二维码，手机 QQ 扫码后 Cookie 自动写入，全程无需手动复制

• Cookie Editor 支持：续 Cookie 时可直接粘贴 Cookie Editor 扩展导出的 JSON

• Web 控制台：登录态查看、Cookie 续期、工具在线调用测试

• 安全设计：Bearer Token 鉴权（恒定时间比较）、IP 防爆破（5 次错封 15 分钟）、仅监听 127.0.0.1、凭证文件权限 600

Related MCP server: qzone-mcp

工具列表

快速开始

方式一：Web 控制台（推荐）

# 1. 安装
pip install "mcp>=1.2,<2" requests fastapi uvicorn
cp qqzone_mcp.py qq_login.py webapp.py ~/.qqzone-mcp/   # 目录自定，默认 ~/qqzone-mcp/

# 2. 启动（监听 127.0.0.1:8787）
python3 webapp.py --port 8787

# 3. 打开控制台
#    http://127.0.0.1:8787/qqzone/console（或按你的反代路径）
#    Token 首次启动自动生成，见 config.json 的 "token" 字段

控制台里点「获取二维码」→ 手机 QQ 扫描（摄像头对准屏幕，QQ 不允许识别相册/截图里的登录码）→ 确认登录 → Cookie 自动写入。

二维码约 2 分钟过期；QQ 风控禁止「识别图片」方式扫码，只能摄像头实时扫真实屏幕。

方式二：命令行安装（stdio 模式）

bash install.sh "p_uin=o...; skey=...; p_skey=..." 你的QQ号

接入 MCP 客户端

stdio（本机）：

{
  "mcpServers": {
    "qqzone": {
      "command": "~/.qqzone-mcp/venv/bin/python",
      "args": ["~/.qqzone-mcp/qqzone_mcp.py"]
    }
  }
}

SSE（远程）： 启动 webapp 后，客户端连 http://127.0.0.1:8787/sse，请求头带 Authorization: Bearer <token>。

公网部署（Cloudflare Tunnel + nginx）

1. 服务只监听 127.0.0.1，务必走隧道/反代，不要直接暴露公网

2. nginx 按路径前缀分流（示例）：

location /qqzone/ {
    proxy_pass http://127.0.0.1:8693/;
    proxy_set_header Host $proxy_host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 3600s;
}

3. ⚠️ 若挂在子路径下，前端请求均使用相对路径，无需额外配置

Cookie 过期怎么办

Cookie 无法服务端自动续期（QQ 风控设计如此），两种续法：

1. 扫码：控制台「获取二维码」→ 摄像头扫屏幕，30 秒

2. Cookie Editor：浏览器装 Cookie Editor → 打开 qzone.qq.com → Export as JSON → 粘贴到控制台「续 Cookie」

skey 通常 13 天失效，p_skey（qzone 主要鉴权凭证）约 3090 天；改密码/异地登录会立即作废。

安全须知

• Cookie 等同账号登录凭证：config.json 权限 600，注意服务器安全

• 所有 API 均需 Bearer Token，Token 在 config.json，泄露后删除该字段重启即重新生成

• 不要把 Token 硬编码进任何公开仓库/前端

文件说明

致谢

接口参数与分页逻辑参考自 WuqianShaw/QzoneExporter（GPL-3.0），本项目以 AGPL-3.0 发布，仅供个人学习研究。