Xadeus-QQ-MCP 是一个 QQ MCP（Model Context Protocol）服务器，通过 NapCatQQ（OneBot v11 协议）连接 QQ，为 AI Agent 提供直接操控 QQ 的能力，包括收发消息、管理群聊、收到消息时自动唤醒等。项目由一位 15 岁开发者基于 Amadeus-QQ-MCP 深度优化改造，采用 MIT License。
主要能力
- 通过 NapCatQQ（OneBot v11）连接 QQ，让 AI Agent 直接控制 QQ。
- 收发消息、群聊管理、文件分享。
- 收到新消息时自动唤醒 AI Agent。
- 跨平台支持。
- 提供上下文与历史记录、群组管理、唤醒目标配置等功能。
使用方式
- 安装 NapCat.Shell 和 QQ。
- 配置 NapCat OneBot v11（WebSocket :3001，HTTP :3000）。
- 一键安装（推荐）：自动检测 NapCat、配置 HTTP:3000/WS:3001、创建 Python venv、写入 QQ_OVERRIDE、生成 NapCat 启动脚本、设置窗口唤醒匹配模式。默认 -windowTitle 为 OC,opencode,Administrator,cmd,管理员（逗号分隔，不区分大小写子串匹配窗口标题）。也可通过 Python 方式安装。
- 配置 AI Agent：注意 AI Agent 配置中传入的 --qq 参数在运行时会被忽略，正确方式是在启动 Agent 前设置 QQ_OVERRIDE 环境变量，或直接修改 src/qq_agent_mcp/main.py 中 QQ_OVERRIDE 的默认值。这样做是为了绕过 AI Agent 缓存 MCP 命令的问题——Agent 只在启动时读取一次配置，改配置文件不生效。
- opencode：编辑 ~/.config/opencode/opencode.json。
- Cursor / Claude Desktop / Windsurf：编辑对应 MCP 配置文件。
- 运行 python setup.py 可自动检测并配置所有已安装的 Agent。
- 唤醒目标配置：通过 set_wake_config 配置窗口标题，即可绑定到任意 AI Agent，配置保存在 src/qq_agent_mcp/wake_config.json。
适用场景
- 希望让 AI Agent 接入 QQ 进行消息收发与群管理的用户。
- 需要在收到 QQ 消息时自动唤醒 AI Agent 的场景。
- 使用 opencode、Cursor、Claude Desktop、Windsurf 等支持 MCP 的 AI Agent 的用户。
依赖与限制
- 需要 Python 3.12+（httpx、aiohttp、FastMCP）。
- 需要 NapCat.Shell（QQ + OneBot v11）。
- 使用 Win32 API（ctypes）实现窗口激活与键盘模拟。
- 已知问题与解决方法：可杀死残留 MCP 进程并等待自动重启；如果 Agent 不自动恢复，会提示手动重启。
- 项目基于 Amadeus-QQ-MCP（MIT License）改造。
