Xadeus-QQ-MCP
Xadeus-QQ-MCP connects AI agents to QQ via NapCatQQ (OneBot v11), enabling messaging, group management, automated wake, and scheduling workflows.
💬 Messaging
Send text (with splitting and optional reply wait), images (base64), voice (auto-converted to SILK), and files from URLs to groups or private chats
Wait for replies without sending a message; recall bot-sent messages
📜 Chat Context & History
Retrieve recent messages for one or multiple groups/friends from the in-memory buffer
Render iPhone-style dark mode chat screenshots (base64 PNG)
Compress/archive old messages into summaries to free buffer space
🔔 Auto-Wake System
Add/remove/list wake rules that automatically activate the AI agent window when incoming QQ messages match keywords or target IDs
Enable/disable rules individually or all at once; lock/unlock wake pending state to prevent duplicates
Configure target window title patterns and focus shortcut; diagnose, test, and debug the wake pipeline
⏰ Timer / Scheduler
Add scheduled wake tasks using cron expressions or fixed intervals (with optional one-shot mode); list and remove timers
👥 Group Management
List joined groups and members (with roles, join times, nicknames); get detailed member info
Mute/unmute, kick members, set group nicknames, and send group announcements
🔧 System & Status
Check QQ login and NapCat connection health; list all bot account friends
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 |
Dedup Lock | Prevents duplicate wake during processing. Unlock manually when done |
Persistent Rules | Wake rules saved to |
|
|
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 |
Related MCP server: qq-mcp-server
Architecture
QQ ←→ NapCat (OneBot v11)
↓ WebSocket :3001 / HTTP :3000
Xadeus-QQ-MCP (Python MCP Server)
↓ MCP Protocol
AI Agent (opencode / Cursor / Claude / ...)Quick Start
Prerequisites
Install NapCat.Shell and QQ
Configure NapCat OneBot v11 (WebSocket :3001, HTTP :3000)
One-Click Setup (Recommended)
.\quickstart.ps1 -qq 你的QQ号Auto-detects NapCat, configures HTTP:3000/WS:3001, creates Python venv, writes QQ_OVERRIDE, generates NapCat start script, sets window wake patterns.
Options:
.\quickstart.ps1 -qq 123456 -windowTitle "OC,opencode,cmd" # Custom window patterns
.\quickstart.ps1 -configFile config.json # Config file mode
.\quickstart.ps1 -restart # Kill stale MCP + wait for recoveryDefault -windowTitle: OC,opencode,Administrator,cmd,管理员
(comma-separated substrings, matched case-insensitively against window titles)
Also available via Python:
python setup.py # Interactive mode
python setup.py --qq YOUR_QQ --fast # Non-interactiveManual Setup
git clone https://github.com/mouse114514/Xadeus-QQ-MCP
cd Xadeus-QQ-MCP
# Virtual env
uv venv
uv sync
# Start MCP Server
uv run python -m qq_agent_mcp --qq YOUR_QQConfigure Your AI Agent
Important: The
QQ_OVERRIDEenvironment variable before starting your agent:$env:QQ_OVERRIDE = "YOUR_QQ"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:
{
"mcp": {
"qq-agent": {
"type": "local",
"command": [
"C:\\path\\.venv\\Scripts\\python.exe",
"-m", "qq_agent_mcp",
"--qq", "YOUR_QQ"
],
"enabled": true,
"timeout": 120000
}
}
}Cursor / Claude Desktop / Windsurf — edit the respective MCP config file:
{
"mcpServers": {
"qq-agent": {
"command": "C:\\path\\.venv\\Scripts\\python.exe",
"args": ["-m", "qq_agent_mcp", "--qq", "YOUR_QQ"],
"enabled": true
}
}
}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:
{
"window_title_patterns": ["opencode", "cursor", "claude"],
"focus_shortcut": "ctrl+l"
}Saved to src/qq_agent_mcp/wake_config.json.
MCP Tools
Messaging
Tool | Description |
| Send text with segmentation and optional reply wait |
| Send image (base64) |
| Send voice (base64) |
| Wait for new messages |
Context & History
Tool | Description |
| Recent messages for a group/friend |
| Batch query multiple targets |
| Render chat screenshot (iPhone dark mode style) |
| Archive old messages to summary |
Wake System
Tool | Description |
| Add auto-wake rule (group/private + keywords) |
| Remove wake rule by index |
| List all wake rules |
| Lock/unlock wake to prevent duplicates |
| Enable/disable all or specific rules |
| Configure target window and focus shortcut |
| View current wake config |
| Debug wake monitor state |
Group Management
Tool | Description |
| List joined groups |
| List group members |
| Get member details |
| Mute a member |
| Unmute a member |
| Kick a member |
| Set group nickname |
| Send group notice |
System
Tool | Description |
| Check QQ and NapCat connection |
| List friends |
| Recall bot message |
| Send file from URL |
| Add scheduled wake (cron/interval) |
| Remove timer |
| List all timers |
Known Issues & Workarounds
Issue | Cause | Workaround |
MCP won't restart after crash/kill | opencode has restart backoff; after ~3 kills it stops retrying | Restart your AI agent, or |
Two MCP processes always appear | FastMCP stdio transport spawns parent+child chain | Named mutex prevents duplicate typing (built-in fix) |
Config changes ignored after editing | opencode caches MCP command at startup | Restart opencode, or use |
Wake message doubled | Both processes try to type simultaneously | Fixed via Windows named mutex ( |
Messages from same QQ ignored |
| Removed in current build |
Wake won't fire even with matching rule | Lock ( | Auto-unlock after 5 min, or call |
Restart Helper
.\quickstart.ps1 -restartKills stale MCP processes and waits for auto-restart. If the agent doesn't recover, it prompts you to restart manually.
Tech Stack
Python 3.12+ (httpx, aiohttp, FastMCP)
NapCat.Shell (QQ + OneBot v11)
Win32 API (ctypes) — window activation, keyboard simulation
License
Based on Amadeus-QQ-MCP (MIT License).
中文版
Xadeus-QQ-MCP
由一位 15 岁高中生基于 Amadeus-QQ-MCP 深度优化改造。
QQ MCP (Model Context Protocol) Server — 通过 NapCatQQ (OneBot v11) 协议连接 QQ,为 AI Agent 提供直接操控 QQ 的能力(收发消息、管理群聊、自动唤醒等)。
功能亮点
功能 | 说明 |
Auto-Wake 自动唤醒 | QQ 消息匹配规则时自动激活 AI Agent 窗口。跨平台 — Windows (keybd_event)、macOS (osascript+pbcopy)、Linux (xdotool+xclip)。支持任意客户端 — opencode、Cursor、Claude Desktop、Windsurf,通过 |
Pending 防重复锁 | 唤醒后自动上锁,防止重复唤醒。Agent 干完活后手动解锁 |
规则持久化 | 唤醒规则自动保存到 |
|
|
群管理 | 禁言、解禁、踢人、设名片、发公告 |
文件发送 | 从 URL 下载文件发送到群/私聊 |
消息撤回 | 撤回机器人发送的消息 |
定时任务 | 支持 cron 和间隔两种模式的定时唤醒 |
一键配置 | 自动检测 NapCat、端口、多 Agent 配置 |
架构
QQ ←→ NapCat (OneBot v11)
↓ WebSocket :3001 / HTTP :3000
Xadeus-QQ-MCP (Python MCP Server)
↓ MCP 协议
AI Agent (opencode / Cursor / Claude / ...)快速开始
前置条件
安装 NapCat.Shell 和 QQ
配置 NapCat OneBot v11 (WebSocket :3001, HTTP :3000)
一键配置(推荐)
.\quickstart.ps1 -qq 你的QQ号自动检测 NapCat、配置 HTTP:3000/WS:3001、创建 Python venv、 写入 QQ_OVERRIDE、生成 NapCat 启动脚本、设置窗口唤醒匹配模式。
选项:
.\quickstart.ps1 -qq 123456 -windowTitle "OC,opencode,cmd" # 自定义窗口匹配模式
.\quickstart.ps1 -configFile config.json # 配置文件模式
.\quickstart.ps1 -restart # 杀死残留 MCP + 等待恢复默认 -windowTitle:OC,opencode,Administrator,cmd,管理员
(逗号分隔,不区分大小写子串匹配窗口标题)
Python 版(功能相同):
python setup.py # 交互模式
python setup.py --qq 你的QQ号 --fast # 静默模式手动安装
git clone https://github.com/mouse114514/Xadeus-QQ-MCP
cd Xadeus-QQ-MCP
# 虚拟环境
uv venv
uv sync
# 启动 MCP Server
uv run python -m qq_agent_mcp --qq 你的QQ号配置 AI Agent
重要:AI Agent 配置中的
$env:QQ_OVERRIDE = "你的QQ号"或直接修改
src/qq_agent_mcp/__main__.py:QQ_OVERRIDE的默认值。这样做是为了绕过 AI Agent 缓存 MCP 命令的问题—— Agent 只在启动时读取一次配置,改配置文件不生效。
opencode — 编辑 ~/.config/opencode/opencode.json:
{
"mcp": {
"qq-agent": {
"type": "local",
"command": [
"C:\\path\\.venv\\Scripts\\python.exe",
"-m", "qq_agent_mcp",
"--qq", "你的QQ号"
],
"enabled": true,
"timeout": 120000
}
}
}Cursor / Claude Desktop / Windsurf — 编辑对应 MCP 配置文件:
{
"mcpServers": {
"qq-agent": {
"command": "C:\\path\\.venv\\Scripts\\python.exe",
"args": ["-m", "qq_agent_mcp", "--qq", "你的QQ号"],
"enabled": true
}
}
}运行 python setup.py 可自动检测并配置所有已安装的 Agent。
唤醒目标配置
通过 set_wake_config 配置窗口标题,即可绑定到任意 AI Agent:
{
"window_title_patterns": ["opencode", "cursor", "claude"],
"focus_shortcut": "ctrl+l"
}配置文件保存在 src/qq_agent_mcp/wake_config.json。
MCP 工具一览
消息
工具 | 说明 |
| 发文本消息,支持分段、等待回复 |
| 发图片 |
| 发语音 |
| 等待新消息 |
上下文
工具 | 说明 |
| 查看最近消息 |
| 批量查看多目标 |
| 生成聊天截图(iPhone 深色模式) |
| 压缩缓存 |
唤醒系统
工具 | 说明 |
| 添加唤醒规则(群/私聊 + 关键词) |
| 删除唤醒规则 |
| 查看所有规则 |
| 锁定/解锁唤醒 |
| 启用/禁用规则 |
| 配置窗口标题和快捷键 |
| 查看唤醒配置 |
| 诊断唤醒状态 |
群管理
工具 | 说明 |
| 群列表 |
| 群成员列表 |
| 成员详情 |
| 禁言 |
| 解禁 |
| 踢出 |
| 设群名片 |
| 发群公告 |
系统
工具 | 说明 |
| 检查连接状态 |
| 好友列表 |
| 撤回消息 |
| 发送文件 |
| 添加定时任务 |
| 删除定时任务 |
| 查看所有定时任务 |
已知问题
问题 | 原因 | 解决方法 |
MCP 被杀后无法自启 | opencode 有重启退避策略 | 重启 AI Agent,或 |
总是有两个 MCP 进程 | FastMCP stdio 产生父子进程链 | 内置命名互斥锁解决重复打字 |
改 opencode.json 不生效 | opencode 启动时缓存命令 | 重启 opencode,或用 |
唤醒消息出现双倍字符 | 两个进程同时打字 | 已修复(Windows 命名互斥锁) |
同 QQ 号发消息不唤醒 |
| 已修复(移除 context.py/wake.py 过滤) |
匹配规则但不唤醒 | 唤醒锁 ( | 5 分钟自动解锁,或调用 |
重启助手
.\quickstart.ps1 -restart杀死残留 MCP 进程并等待自动重启。如果 Agent 不自动恢复,会提示你手动重启。
技术栈
Python 3.12+ (httpx, aiohttp, FastMCP)
NapCat.Shell (QQ + OneBot v11)
Win32 API (ctypes) — 窗口激活、键盘模拟
授权
基于 Amadeus-QQ-MCP (MIT License) 改造。
Available Tools
33 toolsadd_timerAIdempotent
Add a timer task that triggers a wake with the given message at scheduled times.
Supports cron expressions and fixed-interval scheduling:
cron_expr: "0 8 * * *" = every day at 8am
interval_seconds: 3600 = every hour
once: if True, auto-removes after first trigger
At least one of cron_expr or interval_seconds must be provided. Use list_timers to see active timers, remove_timer to cancel.
Mutates the timer configuration. Timers persist across restarts.
Inputs: message (required), cron_expr, interval_seconds, once.
add_wake_ruleAIdempotent
Add a wake rule: when a matching message arrives, opencode wakes up.
When a message matches this rule, the agent is activated and the message context is made available. Use add_wake_rule to create rules, list_wake_rules to see them, remove_wake_rule to delete, and set_wake_enabled to toggle.
Rules are persisted to disk and survive restarts. Keywords are optional: empty list matches any message. target_id=None matches any source.
Mutates the wake rule configuration.
Inputs: target_type (required), target_id, keywords, ignore_if_focused.
batch_get_recent_contextARead-onlyIdempotent
Query recent messages for multiple groups/friends in one call.
More efficient than calling get_recent_context multiple times: uses at most 2 OneBot API calls (one for group names, one for friend names) regardless of how many targets you query. Each target's messages are returned independently with errors for unmonitored targets.
Use this when you need to read context from 2+ conversations at once. For a single target, use get_recent_context instead (simpler).
Read-only. No side effects.
Inputs: targets (required), limit.
check_statusARead-onlyIdempotent
Check QQ login status, NapCat connection, and monitored targets.
Returns the bot's QQ account, online status, uptime, list of monitored groups and friends, and buffer statistics. Use this to verify the server is running correctly before calling other tools. Not the same as get_group_list or get_friend_list — this is a health check, not a query.
Read-only. No side effects. Safe to call at any time.
Inputs: no named parameters.
compress_contextADestructive
Compress all buffered messages for a target into a single summary, freeing buffer space.
This is destructive: raw messages are replaced by a compressed summary. Once compressed, individual messages cannot be recovered from the buffer. Use this after get_recent_context when you want to archive old conversations and make room for new messages.
The compression uses the client LLM (via MCP sampling) to generate a concise summary. Falls back to rule-based compression if LLM is unavailable.
Destructive: permanently replaces raw messages with a summary.
Inputs: target (required), target_type.
debug_wake_pipelineARead-onlyIdempotent
Simulate a wake trigger to debug the wake pipeline.
Creates a fake message from the given target_id and target_type and checks: is the callback registered, does any rule match the fake message, is the monitor currently pending or running. Then invokes the callback to exercise the full activation pipeline. The response fields (callback_set, matches_rules, pending, running, callback_invoked) tell you exactly where the pipeline is broken. Use diagnose_wake for a read-only snapshot without triggering the callback.
Read-only with respect to QQ. May invoke the wake callback.
Inputs: target_type, target_id.
diagnose_wakeARead-onlyIdempotent
Return the current state of the wake monitor for debugging.
Shows: whether the monitor is running, all active rules (with target_type, target_id, keywords, enabled state, ignore_if_focused), whether the message callback is registered on the context manager, and total buffered messages across all targets. Use this as the first step when wake is not working — if monitor_created or callback_set is False, the monitor was never initialized. For a more aggressive test that injects a fake message, use debug_wake_pipeline instead.
Read-only. No side effects.
Inputs: no named parameters.
get_friend_listARead-onlyIdempotent
List all QQ friends of the bot account.
Returns user IDs and nicknames. Use this to discover valid friend IDs for send_message or get_recent_context with target_type="private". For group list use get_group_list instead.
Read-only. No side effects.
Inputs: no named parameters.
get_group_listARead-onlyIdempotent
List all QQ groups the bot has joined.
Returns group IDs, names, and member counts for every group the bot is a member of. Use this to discover valid group IDs for send_message, get_recent_context, or other group-targeting tools. For friend list use get_friend_list instead. For batch name resolution use batch_get_recent_context.
Read-only. No side effects.
Inputs: no named parameters.
get_group_member_infoARead-onlyIdempotent
Get detailed info for a specific QQ group member.
Returns: user_id, nickname, card (group nickname), role (owner/ admin/member), join_time (unix timestamp), last_sent_time, level, title (group honorific), and age/gender if available. Unlike get_group_member_list which returns all members, this gives a single member's full profile. Use this to look up a specific user before deciding to mute, kick, or set their card. Use get_group_member_list when you need to enumerate all members.
Read-only. No side effects.
Inputs: group_id (required), user_id (required).
get_group_member_listARead-onlyIdempotent
List all members of a QQ group.
Returns for each member: user_id (QQ number), nickname, card (group nickname), role (owner/admin/member), join_time (unix timestamp), last_sent_time, level, and title (group honorific). Use get_group_member_info for a single member's detailed info. Use get_group_list to discover valid group_id values. The response includes a count field for the number of members. Large groups (>200 members) may be paginated by QQ; the result includes all members QQ returns in one call.
Read-only. No side effects.
Inputs: group_id (required).
get_recent_contextARead-onlyIdempotent
Retrieve recent messages for one group or friend from the in-memory buffer.
Returns buffered messages (backfill from history + real-time via WebSocket) as raw message objects with sender info, content, timestamps, and image URLs. This is the primary tool for reading chat context. For multiple targets at once, use batch_get_recent_context instead (fewer API calls). To archive old messages and free buffer space, use compress_context.
Messages older than the buffer window are lost. Call compress_context periodically to preserve important conversations.
Read-only. No side effects on the chat.
Inputs: target (required), target_type, limit.
get_wake_configARead-onlyIdempotent
Return the current wake configuration (window title patterns, shortcut).
Use set_wake_config to modify these settings. Changes take effect immediately for future wake activations.
Read-only. No side effects.
Inputs: no named parameters.
kick_memberADestructiveIdempotent
Kick a member from a QQ group.
group_id: the QQ group number. user_id: the QQ number to kick. reject_add_request: if True, rejects future join requests from this user. Requires bot to have admin privileges. This is irreversible for the current session — the user can re-join if not rejected. Consider using mute_member (temporary) as a less drastic alternative. The bot cannot kick group owners or admins of equal rank; returns error in those cases.
Destructive: removes a member from the group.
Inputs: group_id (required), user_id (required), reject_add_request.
list_timersARead-onlyIdempotent
List all configured timer tasks.
Shows each timer's index, message, cron expression, interval, once flag, and next run time. Use add_timer to create timers, remove_timer to cancel.
Read-only. No side effects.
Inputs: no named parameters.
list_wake_rulesARead-onlyIdempotent
List all configured wake rules.
Shows each rule's target type, ID, keywords, enabled state, and focus-ignoring setting. Use add_wake_rule to create rules, remove_wake_rule to delete, and set_wake_enabled to toggle.
Read-only. No side effects.
Inputs: no named parameters.
mute_memberBIdempotent
Mute a member in a QQ group.
group_id: the QQ group number. user_id: the QQ number to mute. duration: mute time in seconds (default 600 = 10 minutes). Requires bot to have admin privileges in the group. Use unmute_member to reverse.
Mutates the group by muting a member.
Inputs: group_id (required), user_id (required), duration.
recall_messageADestructiveIdempotent
Recall (delete) a message sent by the bot.
message_id: the message ID to recall (obtained from send_message's or send_image's message_id in the response). Only works for messages sent by the bot itself within approximately 2 minutes of sending, or anytime if the bot has admin/owner privileges in the group. Cannot recall messages sent by other users. Use this to undo accidental sends. The message is permanently deleted for all members.
Destructive: permanently deletes a message.
Inputs: message_id (required).
remove_timerADestructiveIdempotent
Remove a timer task by index.
Use list_timers to get current indices. Timers are renumbered after removal. This permanently deletes the timer.
Destructive: permanently removes a timer.
Inputs: index (required).
remove_wake_ruleADestructiveIdempotent
Remove a wake rule by index.
Use list_wake_rules to get the current indices. Rules are renumbered after removal. This permanently deletes the rule; to temporarily disable, use set_wake_enabled instead.
Destructive: permanently removes a wake rule.
Inputs: index (required).
screenshot_chatARead-onlyIdempotent
Render a QQ-style dark-mode chat screenshot starting from a given message.
Uses Playwright to render messages as an iPhone-style QQ chat screenshot and returns a base64-encoded PNG image. The screenshot starts from the given message_id and renders downward. If messages fit on one screen, earlier messages are prepended to fill it (bottom-aligned). If they overflow, later messages are cut off.
Requires: Playwright browser (lazy-started on first call). If the message_id is not found in the buffer, returns an error.
Use get_recent_context first to find valid message_ids. The screenshot is read-only and does not modify the chat.
Read-only. No side effects on the chat.
Inputs: target (required), message_id (required), target_type.
send_fileA
Download a file from a URL and send it to a QQ group or friend.
Downloads the file to a temporary directory, uploads it to QQ, then cleans up. Supports any file type. For text use send_message, for images use send_image, for audio use send_voice.
Behavior: requires a publicly accessible URL (no auth). Download timeout is 60 seconds. The file is sent as a QQ file attachment.
Mutates the chat by sending a file.
Inputs: target (required), file_url (required), file_name, target_type.
send_group_noticeAIdempotent
Send a group announcement (notice) to a QQ group.
group_id: the QQ group number. content: the announcement text (plain text only, no rich media). Requires bot to have admin privileges. The notice appears in the group's announcement bar for all members. Unlike send_message, this is persistent and visible to members who join later. Avoid posting notices too frequently — QQ may rate-limit or throttle excessive notices.
Mutates the group by posting an announcement.
Inputs: group_id (required), content (required).
send_imageA
Send a base64-encoded image to a QQ group or friend.
For text messages use send_message. For audio use send_voice. For files use send_file. This tool only sends images.
Behavior: same rate limiting and dedup as send_message. The image is sent as a QQ-native image (not a file attachment).
Mutates the chat by sending an image.
Inputs: target (required), image (required), target_type, reply_to.
send_messageA
Send a text message to a QQ group or friend, optionally waiting for a reply.
This is the primary tool for sending text messages. It supports message splitting via </分段> tags or punctuation-based chunking. The message is sent immediately and the bot's own message is written to the buffer.
To split a reply into multiple messages, insert </分段> at split points. For example: "Hi</分段>How are you?" sends two separate messages.
Behavior: rate-limited (60s dedup window), duplicate content within 60s is blocked. After sending, blocks until a reply arrives (unless wait_reply=False). The reply includes the full message objects.
Use send_image for images, send_voice for audio, send_file for files. For a standalone wait without sending, use wait_for_reply.
Inputs: target (required), content (required), target_type, reply_to, +3 more.
send_voiceA
Send a base64-encoded voice message to a QQ group or friend.
NapCat auto-converts common audio formats (MP3, WAV, AMR, OGG, FLAC) to SILK for QQ voice playback. For text use send_message, for images use send_image, for files use send_file.
Behavior: same rate limiting as send_message. Voice messages cannot be replied to (no reply_to parameter).
Mutates the chat by sending a voice message.
Inputs: target (required), audio (required), target_type.
set_member_cardAIdempotent
Set a member's group nickname (card). Empty string clears it.
group_id: the QQ group number. user_id: the QQ number. card: the new nickname text. Requires bot to have admin privileges.
Mutates the member's group card.
Inputs: group_id (required), user_id (required), card.
set_wake_configAIdempotent
Configure the wake target window and focus shortcut.
window_title_patterns: substrings to match against the window title (e.g., ["opencode", "cursor"]). The wake system focuses the first matching window. focus_shortcut: keyboard shortcut to focus the input box (e.g., "ctrl+l"). Changes take effect immediately.
Mutates the wake configuration. Persisted across restarts.
Inputs: window_title_patterns, focus_shortcut.
set_wake_enabledAIdempotent
Enable or disable a specific wake rule (or all rules if index is None).
Use list_wake_rules to see current indices and states. Disabled rules are skipped during wake matching but remain in the configuration. Use remove_wake_rule to permanently delete a rule.
Mutates the wake rule configuration.
Inputs: index (required), enabled (required).
set_wake_pendingAIdempotent
Manually set the wake pending state to block or allow new wakes.
When pending=True, incoming messages will NOT trigger wake even if they match a rule. When pending=False, messages trigger wake normally. Use this to prevent duplicate wakes while the agent is already working.
Mutates the wake monitor state.
Inputs: pending (required).
test_wake_activationAIdempotent
Manually trigger the wake activation sequence to verify it works.
Sends a test keystroke to the opencode window. Use this to verify the wake system is functional. On Linux, this always returns False (wake is Windows-only). Does not affect any QQ messages.
Read-only with respect to QQ. May type text into opencode window.
Inputs: no named parameters.
unmute_memberAIdempotent
Unmute a member in a QQ group (set mute duration to 0).
group_id: the QQ group number. user_id: the QQ number to unmute. Requires bot to have admin privileges. Use mute_member to mute. Unmuting a member who is not muted is a no-op (returns success). Call get_group_member_list first to verify a member is currently muted before deciding to unmute.
Mutates the group by unmuting a member.
Inputs: group_id (required), user_id (required).
wait_for_replyARead-onlyIdempotent
Block until a new message arrives from a specific group or friend.
Use this as a standalone follow-up after send_message (with
wait_reply=False) or when you need to wait for a reply without sending
first. Returns only messages from others (not the bot's own). Times out
after timeout seconds (max 300).
If you want to send a message AND wait for a reply in one call, use send_message with wait_reply=True instead — it's simpler.
Read-only. No side effects on the chat.
Inputs: target (required), target_type, timeout.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 33 tools
Each tool has a clearly distinct purpose, with descriptions explicitly differentiating them (e.g., send_message vs send_image vs send_voice). Overlap is minimal and well-documented.
All tools follow a consistent verb_noun snake_case pattern (e.g., add_timer, list_timers, send_message). No mixing of conventions.
33 tools is high, but the domain (QQ bot management, wake rules, timers, configuration) justifies the count. Still, it feels heavy compared to typical well-scoped sets.
The tool surface covers the core domain comprehensively: messaging, group management, context handling, wake configuration, and debugging. Minor gaps exist (e.g., no message editing), but overall coverage is strong.
Maintenance
Related MCP Connectors
MCP server for AI dialogue using various LLM models via AceDataCloud
BeautySpark MCP server for ChatGPT, Claude and other MCP clients
MCP server for Qwen Image 3 AI image generation
MCP server for Hailuo (MiniMax) AI video generation
Related MCP Servers
- AlicenseAqualityCmaintenanceAn MCP server that enables AI clients to send and receive QQ messages through NapCatQQ (OneBot v11) for both private and group chats. It supports message context management, real-time WebSocket listening, and human-like typing simulation.726MIT
- AlicenseNot gradedqualityDmaintenanceA MCP server that exposes QQ bot capabilities over Streamable HTTP, enabling clients to query bot status, read group and friend info, fetch chat history, and send group/private text messages.3MIT
- AlicenseBqualityCmaintenanceConnects QQ via NapCat OneBot v11 to an Astral Code app-server, exposing MCP tools for sending messages, files, images, and fetching conversation history.102Apache 2.0
- AlicenseAqualityCmaintenanceExposes NapCat/OneBot v11 QQ-bot APIs as MCP tools for any MCP client, and includes an LLM-driven QQ bot with memory, knowledge base, tool calling, web search, multimodal recognition, and permission controls.45MIT