Skip to main content
Glama
README.md
# 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

C2.5/5.0

Scored across 260 tools

Disambiguation2/5

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.

Naming Consistency2/5

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.

Tool Count1/5

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.

Completeness4/5

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.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues