Skip to content
Back to search

qq-mcp

让 AI 用你自己的 QQ 号做事的 MCP:260 个工具(消息、群、QQ 空间),一个容器部署到云端,掉线自动重新登录

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/zongwei-tang--qq-mcp/badge.svg)](/listings/zongwei-tang--qq-mcp)

HTML

<a href="/listings/zongwei-tang--qq-mcp"><img src="/api/listings/zongwei-tang--qq-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 84 lines
  1. # qq-mcp
  2. **简体中文** | [English](README.en.md)
  3. 让 AI 用**你自己的 QQ 号**做事的 MCP 服务器:读消息、发消息、管群、操作 QQ 空间。260 个工具,一个 Docker 容器,能直接部署到云上(Streamable HTTP),掉线会自动重新登录。
  4. > ⚠️ 用自动化程序操作个人 QQ 违反腾讯用户协议,账号可能被限制。风险自负,请只用于自己的账号。
  5. ## 能做什么
  6. | 类别 | 工具举例 |
  7. | --- | --- |
  8. | 聊天 | `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 看图) |
  9. | 实时 | `get_unread` · `list_recent_chats` · `wait_for_message` · `get_events`(撤回、入群、好友申请…) |
  10. | 群 | 成员列表、禁言、踢人、管理员、群名片、头衔、群公告、群文件、群相册、精华、群待办、加群申请… |
  11. | QQ 空间 | 发说说(带图、可见范围)、删说说、点赞、评论/回复、转发、好友动态、访客、留言板(读/写/回复/删)、相册与照片、点赞名单、浏览/点赞数、亲密度 |
  12. | 兜底 | `onebot_call` 调任意 OneBot 动作 · `qzone_request` 带登录态调任意 QQ 空间接口 |
  13. `node dist/index.js tools` 列出全部工具;`QQ_TOOLSETS` / `QQ_READ_ONLY` 可以只开放一部分。
  14. ## 原理
  15. 容器里跑一个**官方原版 Linux QQ**(虚拟显示器上),[SnowLuma](https://github.com/TomyJan/SnowLuma) 把它变成 OneBot v11 接口,本项目再把每个动作变成 MCP 工具,并加上聊天便捷工具、QQ 空间扩展、扫码登录和登录守护。
  16. 几个现成方案没有解决的点:
  17. - **不需要任何特权**:SnowLuma 用 ptrace 注入 QQ,而大多数云平台(`ptrace_scope=1`)只允许追踪子进程。这里由 SnowLuma 的运行时进程亲自拉起 QQ(`docker/qq-launcher.mjs`),所以在 Railway 这类平台上也能注入。
  18. - **扫码登录走 MCP 或网页**:`qq_login` 返回登录窗口截图;`/login/<token>` 是一个实时刷新的二维码页面。
  19. - **登录守护**:每 30 秒检查一次——记住的账号自动点「登录」、自动关掉下线弹窗、接口卡死就重启 QQ;只有真的需要扫码时才通过 `NOTIFY_WEBHOOK` 通知你。
  20. ## 部署
  21. ### Docker
  22. ```bash
  23. docker build -t qq-mcp .
  24. docker run -d --name qq-mcp --shm-size=1g \
  25. -e MCP_AUTH_TOKEN=$(openssl rand -hex 24) \
  26. -v qq-data:/data -p 8000:8000 qq-mcp
  27. ```
  28. MCP 地址(Streamable HTTP):`http://<host>:8000/mcp/<MCP_AUTH_TOKEN>`,或 `/mcp` 加 `Authorization: Bearer <token>`。
  29. 打开 `http://<host>:8000/login/<MCP_AUTH_TOKEN>`,用手机 QQ 扫码。登录状态保存在 `/data`,重启后自动登录。
  30. ### Railway
  31. 从你自己的仓库副本部署(Dockerfile),挂一个卷到 `/data`,设置 `MCP_AUTH_TOKEN`(至少 24 位随机字符),生成域名即可。`railway.json` 已配置健康检查。
  32. - 一个 QQ 客户端约占 1GB 内存。
  33. - 请从**私有** fork 部署:Railway 的 GitHub 集成会把部署记录和提交状态(项目/服务 ID、控制台链接)写回所连接的仓库。
  34. ### QQ 客户端来源
  35. 腾讯的下载服务器拒绝大多数境外 IP,所以默认从公开镜像 `linyuchen/pmhq` 里复制未修改的 `/opt/QQ`(QQ 3.2.34)。在国内构建可以直接用官方安装包:
  36. ```bash
  37. docker build --build-arg QQ_DEB_URL=<https://im.qq.com/linuxqq/ 上的 .deb 链接> -t qq-mcp .
  38. ```
  39. ## 配置(环境变量)
  40. | 变量 | 说明 |
  41. | --- | --- |
  42. | `MCP_AUTH_TOKEN` | 必填,访问令牌 |
  43. | `NOTIFY_WEBHOOK` | 需要扫码时发通知:Discord webhook、含 `{text}` 的 URL(Bark、Server酱…),或任意接受 JSON POST 的地址 |
  44. | `PUBLIC_URL` | 通知里登录链接的域名(Railway 上自动识别) |
  45. | `QQ_WATCHDOG_INTERVAL` | 登录检查间隔秒数,默认 30;`QQ_WATCHDOG=off` 关闭 |
  46. | `QQ_TOOLSETS` | 只开放这些类别,如 `chat,events,message,qzone,qzone_web` |
  47. | `QQ_READ_ONLY` | `1` = 只开放只读工具 |
  48. | `QQ_DISABLED_TOOLS` | 逗号分隔的要隐藏的工具名 |
  49. | `ONEBOT_WS_URL` / `ONEBOT_ACCESS_TOKEN` | 改连其他 OneBot v11 实现(NapCat、LLBot…),不用自带的 |
  50. ## 开发
  51. ```bash
  52. npm install
  53. npm test # 离线端到端测试(假 OneBot 服务 + 真实 MCP HTTP)
  54. node dist/index.js # stdio 模式
  55. MCP_AUTH_TOKEN=... node dist/index.js serve # HTTP 模式
  56. ```
  57. ## 许可
  58. 本项目代码采用 MIT 许可。它依赖的 [SnowLuma](https://github.com/TomyJan/SnowLuma)(运行时,以及提供动作目录的 npm 包 `@snowluma/mcp`)采用**源码可见、非商业**许可,构建时从官方渠道下载,不包含在本仓库中;商业使用请先取得 SnowLuma 作者授权。QQ 是腾讯的软件。本项目与腾讯、SnowLuma 均无关联。

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.