MCP 服务器

qq-onebot-mcp

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.

README

qq-onebot-mcp

轻量 MCP server：把 QQ（NapCat / OneBot 11）接入任意 MCP 宿主（DSH、Claude、Cursor…）。零 npm 依赖，纯 Node.js ≥ 20，仅用内置 WebSocket。

私聊（白名单老大）→ 消息进 inbox → 宿主 agent 处理（完整工具权限）→ 回复。
群聊 @机器人（白名单群）→ 桥直接用 LLM API 回答，不经 agent、不碰本机。

架构

QQ 老大 ──私聊──▶ NapCat(QQ小号) ──OneBot11/WS:3001──▶ qq-mcp-server.mjs ──MCP──▶ 宿主 agent
                                                                   ▲
                                                              (inbox / 工具)

层	文件	职责
接入	NapCat	QQ 协议 → OneBot 11（WS 3001）
桥	`qq-mcp-server.mjs`	MCP server：工具、排他锁、inbox
桥	`onebot.mjs`	OneBot WS 客户端（零依赖）
桥	`group_llm.mjs`	群聊纯 LLM 直答
唤醒	`qq-listener.mjs`	常驻监听 + 注入宿主席位（可选闭环）
控制	`qqctl.mjs`	进程生命周期（start/stop/status）

快速开始

NapCat：装好并有 QQ 小号登录，开启 OneBot WS（默认 ws://127.0.0.1:3001）。
配置：cp .env.example .env，填 QQ_BOT、QQ_ALLOWED_SENDERS（可加 LLM_API_KEY 开群聊）。
注册 MCP：宿主指向 qq-mcp-server.mjs（stdio）。DSH 用 dsh-bundle/ 模板，见 INSTALL-DSH.md。
上号：告诉 agent「上QQ号」→ 按 skills/qq-online/SKILL.md 走 attach → 等消息 → 回复。

环境变量	必填	含义
`QQ_BOT`	✅	机器人 QQ 号
`QQ_ALLOWED_SENDERS`	✅	私聊白名单，逗号分隔
`ONEBOT_WS_URL`		NapCat WS 地址（默认 `ws://127.0.0.1:3001`）
`QQ_ALLOWED_GROUPS`		静态群白名单（留空=动态）
`LLM_API_KEY` / `LLM_BASE_URL` / `LLM_MODEL`		群聊直答用

.env 已 git 忽略，绝不提交。

MCP 工具

工具	说明
`qq_attach` / `qq_detach`	排他占用 / 释放桥（文件锁，跨宿主；崩溃残留自动抢占）
`qq_wait_inbox`	阻塞等私聊（零轮询，推荐循环用）
`qq_poll_inbox`	取 inbox（可设超时）
`qq_send`	回复当前对话者（仅白名单）
`qq_status`	桥状态
`qq_get_agent_profile`	读 AGENTS.md 角色设定

待机模式：server 启动不连 NapCat，qq_attach 才连、qq_detach 断开 —— 零资源占用。

全自动闭环（可选）

想让 QQ 消息自动唤醒 agent（不用每次喊「上号」）：以独立进程跑 qq-listener.mjs：

DSH_API_URL=http://127.0.0.1:3080 DSH_SESSION_ID=<session-id> \
  node qq-listener.mjs <tag> <workdir> 0

QQ 消息 → 监听器(wait_inbox) → 写入 <workdir>/inbox/ + POST http://127.0.0.1:3080/api/session.prompt
                                                                        │
                                                    agent 自动醒来处理 → <workdir>/outbox/ → qq_send 回复

监听器独立于 agent 会话常驻；session.prompt（mode: queue）把消息注入宿主会话触发回合。
回复放 <workdir>/outbox/*.json（{type:"send", message}），监听器发送（无 chat target 时直连 OneBot WS）。
优雅停止：<workdir> 里写 stop.flag。

⚠️ session.prompt 无鉴权且仅限回环，只在本机信任环境使用。

安全

私聊：仅白名单；陌生私聊丢弃。
群聊：纯 LLM，永不接触本机文件/命令。
qq_send 只能回当前对话者（白名单内）。
白名单用户拉机器人进群 → 自动加白并公告。

个性化

编辑 AGENTS.md（人设/职责/安全边界），桥每会话重新加载，无需重启。

本地隐私（如重要人物关系）可放 data/（git 忽略）并在 AGENTS_MD 里指向它 —— 不上 GitHub。

动态会话发现（闭环）

监听器不再写死 DSH_SESSION_ID：每次收到消息先调 session.list 找 running + 标题含上号/QQ/布卡 的会话，找不到再回退 env。这样「上号」会话被替换/重开后闭环依然生效。

开发

npm test   # 全部入口语法检查

文件

├── qq-mcp-server.mjs   # MCP server（主入口）
├── onebot.mjs          # OneBot WS 客户端
├── group_llm.mjs       # 群聊 LLM 直答
├── bridge.mjs          # 独立触发桥（无 MCP 宿主）
├── bridge-acp.mjs      # ACP 连接器（持久 DSH 会话）
├── qq-listener.mjs     # 闭环监听器
├── qqctl.mjs           # 进程控制
├── dsh-bundle/         # DSH profile bundle 模板
├── skills/qq-online/   # 「上QQ号」技能
├── INSTALL-DSH.md      # 新用户自装指南
└── .env.example        # 配置模板