qq_mcp_server

qq_mcp_server 把当前 NapCat QQ 账号中的多个 COC 跑团群保存到私有 SQLite，并为 ChatGPT 提供彼此隔离的 MCP App。一个群永久对应一个模组、一个当前人物卡和一个群级 MCP 地址；增加新模组时使用新的 QQ 群。可以登记并人工切换多个属于同一玩家的 QQ 号， 账号使用独立 NapCat 登录目录，但共享聊天数据库、人物卡、笔记和模组状态。

QQ 侧始终只读：没有发消息、撤回、禁言、群管理或任意 OneBot 动作透传。MCP 的写操作 只更新本地人物卡、团务笔记与应用配置。

已实现的范围

• 正常运行只消费 NapCat 主动推送的反向 WebSocket 事件；不会轮询群列表、成员或历史。

• 独立采集进程每 60 秒读取一次 NapCat 本地在线状态，不产生 QQ 群或历史网络请求。

• 群访问网页只决定 AI/MCP 是否可以读取该群，不影响被动事件采集。

• 事件会话、心跳与 OneBot 动作全部审计；断线、离线和非正常重启会登记消息缺口。

• QQ 恢复在线后先观察五分钟并连续确认两次，再按全局安全额度渐进补偿历史缺口。

• 显式最近消息刷新有十分钟冷却；完整缺口修复仍受全局 60 秒一页、24 小时 30 页限制。

• 离线时 MCP 仍可读取缓存，但会返回 safe_to_roleplay=false、警告代码和缺口，禁止伪装成实时。

• 登录失效、账号不匹配、切号或人工暂停会持久化熔断，不会自动重启或反复登录 NapCat。

• 可登记多个 QQ 号并经浏览器二次确认切换；每个账号使用独立 NapCat 登录目录。

• 只读取文字、@ 和引用关系；纯媒体消息保存为“未读取的媒体消息”，不解析或保存 URL。

• 一个管理 App：维护账号、群访问、消息缺口、模组、成员角色和群级启停。

• 每个已授权群一个不可猜测、不可修改的 /mcp/groups/{group_key} 端点，工具不接受群参数。

• 固定浅蓝色 23.1.1 Excel 人物卡，只读取 人物卡 工作表；通过 MCP 签发一次性上传、预览、确认链接。

• 动态人物卡和结构化团务笔记可以在一个事务中更新，带版本检查、变更记录和安全定向撤销。

• 群 MCP 可签发一小时有效的只读模组档案页，分页查看 RP 准则、人物卡、笔记、消息和变更。

• 三本私有 COC PDF 离线构建全文索引；运行期只能检索，不能上传 PDF，也没有服务器 LLM。

• Google OAuth 和完整邮箱白名单保护管理 App、群 App 与其签发的短期网页链接。

• Tailscale 私有 NapCat 面板、一次性登录入口，以及浏览器确认的切号/受限恢复流程。

• API 和反向 WebSocket 采集器独立发布；普通 API 更新不会中断采集或重启 NapCat。

• 重新登录稳定五分钟后，白名单且未归档的群会按每分钟一页、每天最多 30 页自动补偿缺口。

• 白名单网页支持归档/恢复；归档群保留历史只读访问和被动入库，不再主动读取 QQ 历史。

不再包含 Dice Echo 解析器、TUI、TXT 导出、旧数据库迁移或关键词命令路由。这是全新数据 库设计，旧人物卡也必须重新上传。

Related MCP server: Xadeus-QQ-MCP

本地启动

需要 Python 3.12+、uv、已登录的 NapCat，以及三本规则书 PDF。

uv sync
uv run qq_mcp_server setup
export ONEBOT_ACCESS_TOKEN='与 NapCat onebot11.json 一致的 token'

uv run qq_mcp_server build-rules \
  --investigator '/home/kscii/Downloads/克苏鲁的呼唤第七版调查员手册1.16.pdf' \
  --keeper '/home/kscii/Downloads/COC7th核心规则书v1.2.1.pdf' \
  --magic '/home/kscii/Downloads/克苏鲁神话魔法大典 0.1.pdf'

uv run qq_mcp_server run

然后连接管理 App /mcp/admin，按自然语言要求它“打开群访问授权”，在一次性网页允许 AI 读取群， 再依次设置模组、玩家/KP/骰娘、上传人物卡并启用群。admin.list_groups 会返回每个群的 固定 MCP URL 和下一步。

连接群 App 后可以说“打开模组面板”，由 trpg.open_campaign_dashboard 返回只绑定 当前群的一小时只读链接。页面不提供编辑能力，所有修改仍通过带版本和审计的 MCP 工具。

人物卡已锁定为同一模板，验证锚点是 J3=玩家、F16=技能名称、F79=物品名称。 山田何也(1).xlsx 与 小林和彦(2).xlsx 已作为真实解析样本测试；空白卡只有填写人物名 和玩家后才能绑定。

MCP 地址

• 管理 App：/mcp/admin

• 群 App：/mcp/groups/{group_key}

建议在 ChatGPT 中只给每个对话连接对应群的 App。群工具里没有 group_id 或 group_key 参数，所以 AI 不能因参数错误越到另一个群。撤销 AI 访问后，其地址立即 返回 404；归档保留历史只读端点，停用只锁跑团工具，被动事件采集仍继续。

不需要另写 Skill、index 或关键词表。两套 MCP Server 已内置简短 instructions，工具名、 描述、读写注解和返回的 next_actions 足够模型从自然语言选择工具。只有在未来出现稳定、 跨 App 的复杂多步流程时，再考虑单独 Skill。

完整接口和配置归属见 配置与操作，实现边界见 架构说明，生产环境见 Google Cloud 部署。

安全与许可

使用非官方 QQ 接入可能触发登录验证或账号风险。请只同步已取得成员同意的群，不要公开 NapCat WebUI、OneBot 端口、规则书 PDF、人物卡链接或无鉴权 MCP。更多边界见 SECURITY.md。项目使用 MIT License。