qq-onebot-mcp

Servidor MCP ligero: conecta QQ (NapCat / OneBot 11) a cualquier host MCP (DSH, Claude, Cursor…). Cero dependencias npm, Node.js puro ≥ 20, solo usa WebSocket integrado.

• Mensajes privados (lista blanca de administradores) → los mensajes entran en la bandeja de entrada → el agente del host los procesa (permisos completos de herramientas) → responde.

• Menciones @bot en chats de grupo (grupos en lista blanca) → el puente responde directamente con la API de LLM, sin pasar por el agente ni tocar la máquina local.

Arquitectura

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

Related MCP server: NapCat MCP Server

Inicio rápido

1. NapCat: instálalo y ten una cuenta QQ secundaria iniciada, activa OneBot WS (por defecto ws://127.0.0.1:3001).

2. Configuración: cp .env.example .env, rellena QQ_BOT, QQ_ALLOWED_SENDERS (puedes añadir LLM_API_KEY para activar los chats de grupo).

3. Registra MCP: el host apunta a qq-mcp-server.mjs (stdio). DSH usa la plantilla dsh-bundle/, consulta INSTALL-DSH.md.

4. Conéctate: dile al agente «conéctate a QQ» → sigue skills/qq-online/SKILL.md para el attach → espera mensajes → responde.

.env está en git ignore, nunca se sube.

Herramientas MCP

Modo en espera: el servidor no se conecta a NapCat al iniciar; solo se conecta con qq_attach y se desconecta con qq_detach — cero consumo de recursos.

Bucle automático completo (opcional)

¿Quieres que los mensajes de QQ despierten automáticamente al agente (sin tener que decir «conéctate» cada vez)? Ejecuta qq-listener.mjs como proceso independiente:

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

• El listener reside de forma independiente a la sesión del agente; session.prompt (mode: queue) inyecta los mensajes en la sesión del host para activar el turno.

• Las respuestas se guardan en <workdir>/outbox/*.json ({type:"send", message}), y el listener las envía (si no hay chat target, se conecta directamente al WS de OneBot).

• Detención limpia: escribe stop.flag en <workdir>.

⚠️ session.prompt no tiene autenticación y solo está limitado a loopback; úsalo solo en entornos locales de confianza.

Seguridad

• Mensajes privados: solo lista blanca; los mensajes privados desconocidos se descartan.

• Chats de grupo: solo LLM, nunca toca archivos o comandos de la máquina local.

• qq_send solo puede responder al interlocutor actual (dentro de la lista blanca).

• Si un usuario de la lista blanca añade al bot a un grupo → se añade automáticamente a la lista blanca y se anuncia.

Personalización

Edita AGENTS.md (personalidad / responsabilidades / límites de seguridad); el puente lo recarga en cada sesión, sin necesidad de reiniciar.

La privacidad local (como relaciones personales importantes) puede ir en data/ (git ignore) y referenciarse desde AGENTS_MD — no se sube a GitHub.

Descubrimiento dinámico de sesiones (bucle)

El listener ya no tiene DSH_SESSION_ID fijo: cada vez que recibe un mensaje, primero llama a session.list para buscar una sesión en ejecución + cuyo título contenga 上号/QQ/布卡; si no la encuentra, recurre a la variable de entorno. Así, si la sesión «conéctate» se reemplaza o se reabre, el bucle sigue funcionando.

Desarrollo

npm test   # 全部入口语法检查

Archivos

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

Licencia

MIT