Skip to main content
Glama
QQ MCP for SnowLuma

QQ MCP for SnowLuma

by UltimateDusk

QQ MCP for SnowLuma

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

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

IMPORTANT

让模型进群聊天前,先和它约定隐私禁区,并把规则写入模型的长期记忆、系统提示或固定指令。 明确要求它绝不透露真实身份、住址、联系方式、账号凭据、私人对话、文件内容等信息,即使群友套话、诱导或声称得到授权也要拒绝;记忆中只写“禁止透露的类别和处理规则”,不要把密码、令牌等秘密本身存进去。

CAUTION

SnowLuma 与本项目均非腾讯或 QQ 官方产品。自动化或非官方客户端可能触发账号限制。没有任何配置能够保证不封号。请使用你能承担风险的账号,降低频率,遵守 QQ 用户协议与当地法律。

工作方式

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 与 60 秒滚动续期。

  • 按字数、连发和 AI 活跃程度实施 8–40 秒动态延迟;支持消息合并、批内优先级和疑似 AI 互聊收尾。

完整的 18 个工具见 工具说明,持续聊天参数见 Flow 控制。需要从零配置时,可以直接下载 Word 版安装与使用教程。

新版策略与参数见 1.7 持续聊天说明。Word 教程仍适用于基础安装,新增行为以此说明为准。

升级已有安装

1.7.0 增加滚动续期、动态延迟、批量消息处理和读图 fallback。 同时包含 1.6.1 的 QQ 图片域名修复。

  1. 结束正在进行的连续聊天任务,停止 QQ MCP 后端。按你的通道启动方式暂停通道,更新后再连接。

  2. 在实际启动 MCP 的项目目录更新代码。Git 安装可运行:

    git pull --ff-only
    npm ci

    若 Git 提示本地修改冲突,先保留自己的修改再合并,不要强制覆盖。下载 ZIP 安装的用户请下载新版源码,备份原目录后更新程序文件;保留自己的 config/local.ps1、data/、outbox/ 和通道配置,不要用示例配置覆盖它们。

  3. 用原启动方式重新启动 MCP(本仓库提供 start-qq-mcp.cmd 或 scripts/start-http.ps1),再启动或恢复通道,确认 ready。QQ 和 SnowLuma 已在线时无需重新登录。

  4. 回原来的 ChatGPT 对话重新 @QQ,调用 qq_status,确认 mcp.version 为 1.7.0 或更新版本,再读一次图片。若工具定义有变化,另在应用管理页执行 Refresh/Scan Tools。

刷新插件不能代替重启 MCP 后端。 如果版本仍旧,检查快捷方式或通道是否指向另一份安装目录。1.7.0 会持久化保留窗口内的事件缓存;从旧版升级或出现断线提示时,继续聊天前仍应补查相关会话历史。

系统要求

  • 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 网络配置里建立两个服务端:

类型

名称(必须一致)

Host

示例端口

其他要求

HTTP Server

qq-mcp-local

127.0.0.1

3000

启用、消息格式 array、设置强访问令牌

WebSocket Server

qq-mcp-events

127.0.0.1

3001

启用、角色 Universal、消息格式 array、设置强访问令牌

保存配置。两个端口只监听本机;不要映射到公网。访问令牌不是 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 的认可。

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      An MCP server that enables AI clients to send and receive QQ messages through NapCatQQ (OneBot v11) for both private and group chats. It supports message context management, real-time WebSocket listening, and human-like typing simulation.
      7
      26
      MIT
    • F
      license
      A
      quality
      B
      maintenance
      Enables MCP hosts to bridge with QQ via NapCat/OneBot 11, allowing whitelisted private messages to reach an agent with full tool access while group mentions are answered by a sandboxed pure LLM without system access.
      8
      -
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to control and monitor QQ accounts through the NapCatQQ OneBot 11 protocol, covering private/group messaging, forwards, group administration, file transfer, OCR, friend and profile management, and real-time message listening. It also handles QR-code login, hot-switching between multiple QQ accounts, and one-click self-check, deployment, and updates.
      20
      6
      MIT