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 / 工具)

Related MCP server: NapCat MCP Server

빠른 시작

1. NapCat: 설치하고 QQ 부계정으로 로그인, OneBot WS 활성화(기본 ws://127.0.0.1:3001).

2. 설정: cp .env.example .env, QQ_BOT, QQ_ALLOWED_SENDERS 입력(LLM_API_KEY 추가 시 그룹 채팅 활성화).

3. MCP 등록: 호스트가 qq-mcp-server.mjs(stdio)를 가리키게 함. DSH는 dsh-bundle/ 템플릿 사용, INSTALL-DSH.md 참조.

4. 접속: agent에게 "QQ 접속" 지시 → skills/qq-online/SKILL.md에 따라 attach → 메시지 대기 → 답장.

.env는 git에서 무시되며 절대 커밋하지 않음.

MCP 도구

대기 모드: 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        # 配置模板

License

MIT