# QQZone MCP Server

把 QQ 空间数据接口封装为 MCP 工具，支持 **扫码登录**、**Web 控制台**、**SSE 远程接入**。基于开源 [QzoneExporter](https://github.com/WuqianShaw/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

## 工具列表

| 工具 | 功能 |
|---|---|
| `whoami` | 检查 Cookie 登录态 |
| `set_cookie` | 更新 Cookie（过期后无需重启） |
| `profile` | 资料卡（昵称/签名/生日/所在地等） |
| `space_stats` | 日志/说说/相册数量 |
| `shuoshuo` | 分页读说说（可带评论） |
| `shuoshuo_search` | 按关键词搜索说说 |
| `albums` | 相册列表元数据 |
| `msgboard` | 留言板 |

## 快速开始

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

```bash
# 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
bash install.sh "p_uin=o...; skey=...; p_skey=..." 你的QQ号
```

## 接入 MCP 客户端

**stdio（本机）：**

```json
{
  "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 按路径前缀分流（示例）：

```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` 通常 1~3 天失效，`p_skey`（qzone 主要鉴权凭证）约 30~90 天；改密码/异地登录会立即作废。

## 安全须知

- Cookie 等同账号登录凭证：config.json 权限 600，注意服务器安全
- 所有 API 均需 Bearer Token，Token 在 config.json，泄露后删除该字段重启即重新生成
- 不要把 Token 硬编码进任何公开仓库/前端

## 文件说明

| 文件 | 说明 |
|---|---|
| `qqzone_mcp.py` | MCP Server 主体（stdio + `--http` 模式） |
| `qq_login.py` | QQ 扫码登录协议链（xlogin → ptqrshow → ptqrlogin → check_sig） |
| `webapp.py` | Web 控制台 + SSE（FastAPI） |
| `install.sh` | stdio 模式一键安装脚本 |

## 致谢

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