mouse114514/Xadeus-QQ-MCP

> Built by a 15-year-old developer, based on Amadeus-QQ-MCP.
QQ MCP (Model Context Protocol) Server — connects to QQ via NapCatQQ (OneBot v11), giving AI agents direct control over QQ (send/receive messages, group management, auto-wake on incoming messages, and more).
---
Features
| Feature | Description |
|---------|-------------|
| **Auto-Wake** | Incoming QQ messages matching rules trigger the AI agent window automatically. **Cross-platform** — Windows (keybd_event), macOS (osascript+pbcopy), Linux (xdotool+xclip). Supports any client — opencode, Cursor, Claude Desktop, Windsurf — configure via set_wake_config |
| **Dedup Lock** | Prevents duplicate wake during processing. Unlock manually when done |
| **Persistent Rules** | Wake rules saved to wake_rules.json, auto-loaded on restart |
| **wait_for_reply Built-in** | send_message waits for reply by default |
| **Group Moderation** | Mute, unmute, kick, set card, send notices |
| **File Sending** | Send any file from URL to QQ groups/private chats |
| **Message Recall** | Recall bot-sent messages |
| **Timer Scheduler** | Cron or interval-based timed wake |
| **One-Click Setup** | Auto-detect NapCat, configure ports, update agent configs |
Architecture
Quick Start
Prerequisites
1. Install NapCat.Shell and QQ
2. Configure NapCat OneBot v11 (WebSocket :3001, HTTP :3000)
One-Click Setup (Recommended)
Auto-detects NapCat, configures HTTP:3000/WS:3001, creates Python venv,
writes QQ_OVERRIDE, generates NapCat start script, sets window wake patterns.
Options:
Default -windowTitle: OC,opencode,Administrator,cmd,管理员
(comma-separated substrings, matched case-insensitively against window titles)
Also available via Python:
Manual Setup
Configure Your AI Agent
> **Important**: The --qq argument passed by your AI agent config is **ignored** at runtime.
> Instead, set QQ_OVERRIDE environment variable before starting your agent:
>
> Or edit the fallback value in src/qq_agent_mcp/__main__.py:QQ_OVERRIDE.
>
> This works around AI agents that cache the MCP command at startup
> and ignore subsequent config file changes.
**opencode** — edit ~/.config/opencode/opencode.json:
**Cursor / Claude Desktop / Windsurf** — edit the respective MCP config file:
*Or just run python setup.py — it detects all installed agents automatically.*
Wake Target Configuration
Use set_wake_config to bind to any AI agent window:
Saved to src/qq_agent_mcp/wake_config.json.
MCP Tools
Messaging
| Tool | Description |
|------|-------------|
| send_message | Send text with segmentation and optional reply wait |
| send_image | Send image (base64) |
| send_voice | Send voice (base64) |
| wait_for_reply | Wait for new messages |
Context & History
| Tool | Description |
|------|-------------|
| get_recent_context | Recent messages for a group/friend |
| batch_get_recent_context | Batch query multiple targets |
| screenshot_chat | Render chat screenshot (iPhone dark mode style) |
| compress_context | Archive old messages to summary |
Wake System
| Tool | Description |
|------|-------------|
| add_wake_rule | Add auto-wake rule (group/private + keywords) |
| remove_wake_rule | Remove wake rule by index |
| list_wake_rules | List all wake rules |
| set_wake_pending | Lock/unlock wake to prevent duplicates |
| set_wake_enabled | Enable/disable all or specific rules |
| set_wake_config | Configure target window and focus shortcut |
| get_wake_config | View current wake config |
| diagnose_wake | Debug wake monitor state |
Group Management
| Tool | Description |
|------|-------------|
| get_group_list | List joined groups |
| get_group_member_list | List group members |
| get_group_member_info | Get member details |