qq-onebot-mcp

Leichter MCP-Server: bindet QQ (NapCat / OneBot 11) an beliebige MCP-Hosts (DSH, Claude, Cursor…) an. Null npm-Abhängigkeiten, reines Node.js ≥ 20, nur mit eingebautem WebSocket.

• Privatnachrichten (Whitelist-Chef) → Nachrichten gehen in die Inbox → Host-Agent verarbeitet (volle Tool-Berechtigung) → Antwort.

• Gruppenchat @Bot (Whitelist-Gruppen) → die Brücke antwortet direkt über die LLM-API, ohne Agent, ohne lokalen Zugriff.

Architektur

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

Related MCP server: NapCat MCP Server

Schnellstart

1. NapCat: installieren und mit einem QQ-Zweitkonto anmelden, OneBot WS aktivieren (Standard ws://127.0.0.1:3001).

2. Konfiguration: cp .env.example .env, QQ_BOT, QQ_ALLOWED_SENDERS ausfüllen (optional LLM_API_KEY für Gruppenchat).

3. MCP registrieren: Host zeigt auf qq-mcp-server.mjs (stdio). DSH nutzt die dsh-bundle/-Vorlage, siehe INSTALL-DSH.md.

4. Einloggen: dem Agent sagen „Geh auf QQ" → nach skills/qq-online/SKILL.md attach → auf Nachrichten warten → antworten.

.env ist git-ignoriert, niemals committen.

MCP-Tools

Standby-Modus: Der Server verbindet sich beim Start nicht mit NapCat, erst qq_attach verbindet, qq_detach trennt — null Ressourcenverbrauch.

Vollautomatischer geschlossener Kreislauf (optional)

Möchte man, dass QQ-Nachrichten den Agent automatisch aufwecken (ohne jedes Mal „Einloggen" zu rufen): qq-listener.mjs als eigenen Prozess starten:

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

• Der Listener läuft unabhängig von der Agent-Sitzung dauerhaft; session.prompt (mode: queue) injiziert Nachrichten in die Host-Sitzung und löst eine Runde aus.

• Antworten werden in <workdir>/outbox/*.json gelegt ({type:"send", message}), der Listener sendet sie (ohne Chat-Target direkt über OneBot WS).

• Sauberer Stopp: stop.flag in <workdir> schreiben.

⚠️ session.prompt hat keine Authentifizierung und ist nur auf Loopback beschränkt — nur in vertrauenswürdiger lokaler Umgebung verwenden.

Sicherheit

• Privatchat: nur Whitelist; fremde Privatnachrichten werden verworfen.

• Gruppenchat: reine LLM, berührt niemals lokale Dateien/Befehle.

• qq_send kann nur dem aktuellen Gesprächspartner antworten (innerhalb der Whitelist).

• Whitelist-Benutzer ziehen den Bot in eine Gruppe → automatische Freischaltung und Bekanntmachung.

Personalisierung

AGENTS.md bearbeiten (Persönlichkeit/Aufgaben/Sicherheitsgrenzen), die Brücke lädt es pro Sitzung neu, kein Neustart nötig.

Lokale private Daten (z. B. wichtige Personenbeziehungen) können in data/ (git-ignoriert) abgelegt und in AGENTS_MD darauf verwiesen werden — nicht auf GitHub.

Dynamische Sitzungserkennung (geschlossener Kreislauf)

Der Listener schreibt DSH_SESSION_ID nicht mehr fest: Bei jeder Nachricht ruft er zuerst session.list auf, um eine laufende Sitzung mit Titel enthält 上号/QQ/布卡 zu finden, sonst Fallback auf env. So bleibt der geschlossene Kreislauf auch aktiv, wenn die „Einloggen"-Sitzung ersetzt/neu geöffnet wird.

Entwicklung

npm test   # 全部入口语法检查

Dateien

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

Lizenz

MIT