qq-onebot-mcp

A lightweight MCP server that connects QQ (NapCat / OneBot 11) to any MCP host (DSH, Claude, Cursor...). Zero npm dependencies, pure Node.js ≥ 20, using only the built-in WebSocket.

• Private chat (whitelisted owner) → messages go to inbox → host agent processes (full tool permissions) → replies.

• Group chat @bot (whitelisted groups) → bridge answers directly via LLM API, without going through the agent, without touching the local machine.

Architecture

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

Related MCP server: NapCat MCP Server

Quick Start

1. NapCat: Install it and log in with a QQ alt account, enable OneBot WS (default ws://127.0.0.1:3001).

2. Configuration: cp .env.example .env, fill in QQ_BOT, QQ_ALLOWED_SENDERS (optionally add LLM_API_KEY to enable group chat).

3. Register MCP: Point the host to qq-mcp-server.mjs (stdio). For DSH use the dsh-bundle/ template, see INSTALL-DSH.md.

4. Go online: Tell the agent "get on QQ" → follow skills/qq-online/SKILL.md to attach → wait for messages → reply.

.env is git-ignored, never commit it.

MCP Tools

Standby mode: the server does not connect to NapCat on startup; it connects only on qq_attach and disconnects on qq_detach — zero resource usage.

Fully Automatic Closed Loop (Optional)

To have QQ messages automatically wake the agent (no need to say "get online" every time): run qq-listener.mjs as a separate process:

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 回复

• The listener stays resident independently of the agent session; session.prompt (mode: queue) injects messages into the host session to trigger a turn.

• Replies go to <workdir>/outbox/*.json ({type:"send", message}), and the listener sends them (connects directly to OneBot WS when there is no chat target).

• Graceful stop: write stop.flag in <workdir>.

⚠️ session.prompt has no authentication and is loopback-only; use it only in a trusted local environment.

Security

• Private chat: whitelist only; unknown private messages are discarded.

• Group chat: pure LLM, never touches local files/commands.

• qq_send can only reply to the current conversation partner (within the whitelist).

• When a whitelisted user pulls the bot into a group → auto-whitelist and announce.

Personalization

Edit AGENTS.md (persona/responsibilities/security boundaries); the bridge reloads it every session, no restart needed.

Local privacy (e.g., important personal relationships) can go in data/ (git-ignored) and be referenced from AGENTS_MD — never uploaded to GitHub.

Dynamic Session Discovery (Closed Loop)

The listener no longer hardcodes DSH_SESSION_ID: on each incoming message it first calls session.list to find a running session whose title contains 上号/QQ/布卡, and falls back to env if none is found. This way the closed loop still works after the "get online" session is replaced or reopened.

Development

npm test   # 全部入口语法检查

Files

├── 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        # 配置模板

License

MIT