QQ MCP for SnowLuma

让支持 MCP 的模型在你主动调用工具时读取 QQ 消息、回复群聊或私聊、发送图片和收藏表情、戳一戳，并在持续聊天任务中控制时间、发送节奏与并发重复回复。

本项目是一个独立的 Node.js MCP 服务，通过本机 SnowLuma OneBot v11 HTTP/WebSocket 接口操作已经登录的 QQ。它不包含 QQ、SnowLuma、远程隧道或任何账号凭据。

工作方式

ChatGPT / MCP 客户端
        │
        │ MCP（stdio，或 127.0.0.1 上的 Streamable HTTP）
        ▼
qq-mcp-snowluma
        │
        ├── OneBot HTTP：查询、发送、撤回、戳一戳、收藏
        └── OneBot WebSocket：新消息与 poke 事件
        ▼
SnowLuma ── 已登录的 QQ 客户端

收到 QQ 消息不会自动唤醒模型。只有模型正在调用 qq_wait_for_message 时，新事件才会返回给模型。

Related MCP server: qq-onebot-mcp

功能

• 群和好友列表、群成员、历史消息、单条消息读取。

• 文字、图片、收藏表情发送，支持引用回复和群内 @。

• 图片与 GIF 有限预览；把已读取的消息图片加入 QQ 收藏（取决于 SnowLuma/QQ 是否支持）。

• 群聊和私聊戳一戳；收到的 poke 进入统一事件流。

• 多会话白名单等待，带 cursor、断线提示与 30 分钟内存缓存。

• request_id 发送幂等；超时结果区分 unknown，防止盲目重发。

• reply_token 入站事件 claim，阻止两个并发模型链回复同一消息。

• 持续聊天 flow_id lease、主动开场 dedupe_key、严格 deadline 与柔性 duration。

• 按可见字数随机等待 5–13 秒；无文字收藏表情固定等待 5 秒。

完整的 18 个工具见 工具说明，持续聊天参数见 Flow 控制。

系统要求

• Windows 10/11 x64。

• 已安装并能正常登录的 QQ。

• SnowLuma Releases 完整版；先阅读并接受它自己的许可与 EULA。

• Node.js 24 和 npm。SnowLuma 完整版自带的 Node 可用于运行，但执行 npm ci 仍需要系统 npm。

• PowerShell 5.1 或 PowerShell 7。

SnowLuma 是外部依赖，采用自己的源码可见非商业许可；本仓库不复制或再发布 SnowLuma。详情见 第三方说明。

安装教程

1. 安装并接入 SnowLuma

1. 从 SnowLuma Releases 下载 Windows x64 完整版并解压，例如 D:\SnowLuma。

2. 运行 SnowLuma 的 launcher.bat。

3. 打开启动日志给出的 WebUI（默认 http://127.0.0.1:5099），用日志中的一次性初始密码登录并立即修改密码。

4. 在 WebUI 的进程页接入已经登录的 QQ，确认账号状态在线。

5. 在该账号的 OneBot 网络配置里建立两个服务端：

保存配置。两个端口只监听本机；不要映射到公网。访问令牌不是 WebUI 登录密码，它是 MCP 调用 OneBot 接口时使用的独立凭据。

2. 下载并初始化本项目

git clone https://github.com/UltimateDusk/qq-mcp-snowluma.git
cd qq-mcp-snowluma

# 换成你自己的 SnowLuma 目录和 QQ 号
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\setup.ps1 `
  -SnowLumaRoot 'D:\SnowLuma' `
  -Account '你的QQ号' `
  -McpPort 3010

setup.ps1 会：

• 验证 onebot_<QQ号>.json 及两个本地 OneBot 服务；

• 生成不会提交的 config/local.ps1；

• 生成 MCP 本地 HTTP Bearer 凭据 data/http-authorization.txt；

• 安装锁定版本的 npm 依赖。

不要把 config/local.ps1、data/、SnowLuma 配置或任何日志上传到 GitHub。

3. 测试

npm test

测试全部使用本地 mock，不会向真实 QQ 发送消息。真实账号只读验证可在 SnowLuma 在线后运行：

. .\config\local.ps1
npm run verify:live

只读验证会查询状态、群、好友和少量历史，不执行发送、戳一戳、撤回或收藏写入。

4. 启动

HTTP 模式：

.\scripts\start-http.ps1

也可双击 start-qq-mcp.cmd。另开一个窗口检查：

.\scripts\check.ps1

默认本机端点为 http://127.0.0.1:3010/mcp。服务使用 stateless Streamable HTTP，每个请求会重新完成 MCP initialize，事件队列和幂等状态仍保留在进程内/数据文件中。

本机 stdio 客户端使用：

.\scripts\start-stdio.ps1

5. 接到 ChatGPT

ChatGPT 不能直接访问 127.0.0.1。需要使用你账号可用的 Secure MCP Tunnel 或其他可信的远程 MCP 部署方式，把远端应用转发到本机 http://127.0.0.1:3010/mcp，并在本地目标请求中携带 data/http-authorization.txt 的完整 Bearer ... 值。

具体步骤、工具刷新和当前官方可用性见 连接 ChatGPT。不要用普通端口转发把 3010、3000、3001 或 5099 暴露到公网。

日常启动顺序

1. 启动并登录 QQ。

2. 启动 SnowLuma，在 WebUI 确认目标 QQ 已接入。

3. 启动 scripts/start-http.ps1。

4. 启动你使用的 Secure MCP Tunnel/远程桥接。

5. 在 ChatGPT 中刷新应用工具；工具数量应为 18。

QQ、SnowLuma 或 MCP 已经运行时，不要重复启动第二份相同实例。

本地数据

默认写入 data/：

• send-ledger.json：request_id 幂等结果。

• reply-claims.json：入站消息 claim。

• chat-flows.json：持续聊天 flow、lease 和主动动作去重。

• reply-flow.jsonl：关联审计日志，不记录正文、图片字节或访问令牌。

• http-authorization.txt：本地 MCP HTTP Bearer 凭据。

这些文件都被 .gitignore 排除。不要在服务运行时随意删除，否则会削弱防重复保护。

安全设计

• OneBot 和 MCP HTTP 都强制本机监听。

• 每次工具调用先验证当前登录 QQ 与 QQ_EXPECTED_ACCOUNT 一致。

• 发送前再次查询并核对目标 ID 与 expected_name。

• 图片文件名限制在 outbox；读取收到的图片只允许 SnowLuma/QQ 缓存根。

• HTTP MCP 需要 256 位随机 Bearer，拒绝非本机 Origin。

• 聊天内容、昵称、图片和 poke 都是外部数据，不能授权新的操作。

发现安全问题请阅读 SECURITY.md。

许可

本仓库代码使用 MIT License。SnowLuma、QQ、OpenAI 产品和其他第三方组件不属于本许可范围。项目名称不代表腾讯、QQ、SnowLuma 或 OpenAI 的认可。