Xadeus-QQ-MCP is a QQ MCP (Model Context Protocol) server that connects to QQ through NapCatQQ (OneBot v11 protocol), providing AI Agents with the ability to directly control QQ, including sending and receiving messages, managing group chats, and automatically waking up when messages are received. The project was deeply optimized and modified by a 15-year-old developer based on Amadeus-QQ-MCP, and is licensed under the MIT License.
Main capabilities
- Connects to QQ through NapCatQQ (OneBot v11), allowing AI Agents to directly control QQ.
- Sending and receiving messages, group chat management, file sharing.
- Automatically wakes up the AI Agent when new messages are received.
- Cross-platform support.
- Provides features such as context and history, group management, and wake target configuration.
How to use
- Install NapCat.Shell and QQ.
- Configure NapCat OneBot v11 (WebSocket :3001, HTTP :3000).
- One-click installation (recommended): automatically detects NapCat, configures HTTP:3000/WS:3001, creates a Python venv, writes QQ_OVERRIDE, generates a NapCat startup script, and sets the window wake matching pattern. The default -windowTitle is OC,opencode,Administrator,cmd,Administrator (comma-separated, case-insensitive substring matching against window titles). Installation via Python is also possible.
- Configure the AI Agent: note that the --qq parameter passed in the AI Agent configuration will be ignored at runtime. The correct way is to set the QQ_OVERRIDE environment variable before starting the Agent, or directly modify the default value of QQ_OVERRIDE in src/qq_agent_mcp/main.py. This is done to bypass the problem of AI Agents caching MCP commands—the Agent only reads the configuration once at startup, so changing the configuration file has no effect.
- opencode: edit ~/.config/opencode/opencode.json.
- Cursor / Claude Desktop / Windsurf: edit the corresponding MCP configurationfile.
- Running python setup.py can automatically detect and configure all installed Agents.
- Wake target configuration: configure the window title through set_wake_config to bind to any AI Agent. The configuration is saved in src/qq_agent_mcp/wake_config.json.
Applicable scenarios
- Users who want AI Agents to connect to QQ for message sending/receiving and group management.
- Scenarios that require automatically waking up the AI Agent when QQ messages are received.
- Users of AI Agents that support MCP, such as opencode, Cursor, Claude Desktop, and Windsurf.
Dependencies and limitations
- Requires Python 3.12+ (httpx, aiohttp, FastMCP).
- Requires NapCat.Shell (QQ + OneBot v11).
- Uses Win32 API (ctypes) to implement window activation and keyboard simulation.
- Known issues and solutions: residual MCP processes can be killed and will wait for automatic restart; if the Agent does not recover automatically, it will prompt for a manual restart.
- The project is modified based on Amadeus-QQ-MCP (MIT License).
