qq-mcp
# qq-mcp
**简体中文** | [English](README.en.md)
让 AI 用**你自己的 QQ 号**做事的 MCP 服务器:读消息、发消息、管群、操作 QQ 空间。260 个工具,一个 Docker 容器,能直接部署到云上(Streamable HTTP),掉线会自动重新登录。
> ⚠️ 用自动化程序操作个人 QQ 违反腾讯用户协议,账号可能被限制。风险自负,请只用于自己的账号。
## 能做什么
| 类别 | 工具举例 |
| --- | --- |
| 聊天 | `find_contact` 按名字找人/群 · `read_chat` · `search_chat` · `send_text`(支持 @、引用、表情) · `send_image` / `send_voice` / `send_video` / `send_file` · `reply_to_message` · `forward_messages` 合并转发 · `poke` · `view_image`(让 AI 看图) |
| 实时 | `get_unread` · `list_recent_chats` · `wait_for_message` · `get_events`(撤回、入群、好友申请…) |
| 群 | 成员列表、禁言、踢人、管理员、群名片、头衔、群公告、群文件、群相册、精华、群待办、加群申请… |
| QQ 空间 | 发说说(带图、可见范围)、删说说、点赞、评论/回复、转发、好友动态、访客、留言板(读/写/回复/删)、相册与照片、点赞名单、浏览/点赞数、亲密度 |
| 兜底 | `onebot_call` 调任意 OneBot 动作 · `qzone_request` 带登录态调任意 QQ 空间接口 |
`node dist/index.js tools` 列出全部工具;`QQ_TOOLSETS` / `QQ_READ_ONLY` 可以只开放一部分。
## 原理
容器里跑一个**官方原版 Linux QQ**(虚拟显示器上),[SnowLuma](https://github.com/TomyJan/SnowLuma) 把它变成 OneBot v11 接口,本项目再把每个动作变成 MCP 工具,并加上聊天便捷工具、QQ 空间扩展、扫码登录和登录守护。
几个现成方案没有解决的点:
- **不需要任何特权**:SnowLuma 用 ptrace 注入 QQ,而大多数云平台(`ptrace_scope=1`)只允许追踪子进程。这里由 SnowLuma 的运行时进程亲自拉起 QQ(`docker/qq-launcher.mjs`),所以在 Railway 这类平台上也能注入。
- **扫码登录走 MCP 或网页**:`qq_login` 返回登录窗口截图;`/login/<token>` 是一个实时刷新的二维码页面。
- **登录守护**:每 30 秒检查一次——记住的账号自动点「登录」、自动关掉下线弹窗、接口卡死就重启 QQ;只有真的需要扫码时才通过 `NOTIFY_WEBHOOK` 通知你。
## 部署
### Docker
```bash
docker build -t qq-mcp .
docker run -d --name qq-mcp --shm-size=1g \
-e MCP_AUTH_TOKEN=$(openssl rand -hex 24) \
-v qq-data:/data -p 8000:8000 qq-mcp
```
MCP 地址(Streamable HTTP):`http://<host>:8000/mcp/<MCP_AUTH_TOKEN>`,或 `/mcp` 加 `Authorization: Bearer <token>`。
打开 `http://<host>:8000/login/<MCP_AUTH_TOKEN>`,用手机 QQ 扫码。登录状态保存在 `/data`,重启后自动登录。
### Railway
从你自己的仓库副本部署(Dockerfile),挂一个卷到 `/data`,设置 `MCP_AUTH_TOKEN`(至少 24 位随机字符),生成域名即可。`railway.json` 已配置健康检查。
- 一个 QQ 客户端约占 1GB 内存。
- 请从**私有** fork 部署:Railway 的 GitHub 集成会把部署记录和提交状态(项目/服务 ID、控制台链接)写回所连接的仓库。
### QQ 客户端来源
腾讯的下载服务器拒绝大多数境外 IP,所以默认从公开镜像 `linyuchen/pmhq` 里复制未修改的 `/opt/QQ`(QQ 3.2.34)。在国内构建可以直接用官方安装包:
```bash
docker build --build-arg QQ_DEB_URL=<https://im.qq.com/linuxqq/ 上的 .deb 链接> -t qq-mcp .
```
## 配置(环境变量)
| 变量 | 说明 |
| --- | --- |
| `MCP_AUTH_TOKEN` | 必填,访问令牌 |
| `NOTIFY_WEBHOOK` | 需要扫码时发通知:Discord webhook、含 `{text}` 的 URL(Bark、Server酱…),或任意接受 JSON POST 的地址 |
| `PUBLIC_URL` | 通知里登录链接的域名(Railway 上自动识别) |
| `QQ_WATCHDOG_INTERVAL` | 登录检查间隔秒数,默认 30;`QQ_WATCHDOG=off` 关闭 |
| `QQ_TOOLSETS` | 只开放这些类别,如 `chat,events,message,qzone,qzone_web` |
| `QQ_READ_ONLY` | `1` = 只开放只读工具 |
| `QQ_DISABLED_TOOLS` | 逗号分隔的要隐藏的工具名 |
| `ONEBOT_WS_URL` / `ONEBOT_ACCESS_TOKEN` | 改连其他 OneBot v11 实现(NapCat、LLBot…),不用自带的 |
## 开发
```bash
npm install
npm test # 离线端到端测试(假 OneBot 服务 + 真实 MCP HTTP)
node dist/index.js # stdio 模式
MCP_AUTH_TOKEN=... node dist/index.js serve # HTTP 模式
```
## 许可
本项目代码采用 MIT 许可。它依赖的 [SnowLuma](https://github.com/TomyJan/SnowLuma)(运行时,以及提供动作目录的 npm 包 `@snowluma/mcp`)采用**源码可见、非商业**许可,构建时从官方渠道下载,不包含在本仓库中;商业使用请先取得 SnowLuma 作者授权。QQ 是腾讯的软件。本项目与腾讯、SnowLuma 均无关联。
TDQS
Scored across 260 tools
The surface contains numerous near-duplicate or heavily overlapping tools: send_text/send_message/send_msg/send_private_msg/send_group_msg, forward_messages/forward_friend_single_msg/forward_group_single_msg/send_forward_msg/send_group_forward_msg/send_private_forward_msg/upload_forward_msg, share_peer/send_ark_share/share_group_ex/send_group_ark_share, fetch_emoji_like/get_emoji_likes/get_msg_emoji_likes, and delete_group_file_folder/delete_group_folder appear to do the same thing. An agent would frequently have to guess between aliases and layered wrappers (NapCat-style vs SnowLuma-style vs OneBot-style) with no clear selection rule. Some families (group info, group admin, Qzone) are distinguishable, but the messaging and forwarding clusters are badly blurred.
Names mostly use verb_noun snake_case, but the set mixes prefixes and conventions: qq_login/qq_screenshot/qq_watchdog alongside bare send_text, get_msg, poke, mark_all_as_read, plus odd forms like nc_get_user_status, do_group_album_comment, clean_cache, and duplicate aliases such as get_group_album_list vs get_qun_album_list. There is no single predictable pattern an agent can rely on, and same-purpose tools land in different naming families.
260 tools is far beyond any reasonable agent-facing surface for a QQ client; almost every OneBot action plus Qzone CGI plus raw SSO/credential helpers is exposed individually. Many tools are redundant shims (aliases, escape hatches, capability probes, stream-test helpers) that inflate the list without adding capability. The server would have been far more coherent with a scoped core of 15-25 tools plus one escape hatch.
Coverage is effectively exhaustive: messaging, media, group info/admin/files/albums, friend handling, events, and extensive Qzone read/write operations are all present, with escape hatches (onebot_call, qzone_request, send_packet) filling any remaining gap. The only completeness concerns are minor (some operations only reachable via escape hatches), so the surface itself has no obvious dead ends.