Skip to main content
Glama
Xadeus-QQ-MCP

Xadeus-QQ-MCP

Xadeus-QQ-MCP

Listed on awesome-remote-mcp-servers

Built by a 15-year-old developer, based on Amadeus-QQ-MCP.

Xadeus-QQ-MCP MCP server

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).

Python 3.12+ License: MIT


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

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

  1. Install NapCat.Shell and QQ

  2. Configure NapCat OneBot v11 (WebSocket :3001, HTTP :3000)

.\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 recovery

Default -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-interactive

Manual 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_QQ

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:

$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_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

mute_member

Mute a member

unmute_member

Unmute a member

kick_member

Kick a member

set_member_card

Set group nickname

send_group_notice

Send group notice

System

Tool

Description

check_status

Check QQ and NapCat connection

get_friend_list

List friends

recall_message

Recall bot message

send_file

Send file from URL

add_timer

Add scheduled wake (cron/interval)

remove_timer

Remove timer

list_timers

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 .\quickstart.ps1 -restart

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.json

opencode caches MCP command at startup

Restart opencode, or use QQ_OVERRIDE env var

Wake message doubled

Both processes try to type simultaneously

Fixed via Windows named mutex (Local\XadeusQQ_MCP_WakeTyping)

Messages from same QQ ignored

is_self filter in context.py and wake.py

Removed in current build

Wake won't fire even with matching rule

Lock (_pending) held from previous wake

Auto-unlock after 5 min, or call set_wake_pending(false)

Restart Helper

.\quickstart.ps1 -restart

Kills 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

Listed on awesome-remote-mcp-servers

由一位 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,通过 set_wake_config 配置窗口标题即可

Pending 防重复锁

唤醒后自动上锁,防止重复唤醒。Agent 干完活后手动解锁

规则持久化

唤醒规则自动保存到 wake_rules.json,重启后自动加载

wait_for_reply 一体化

send_message 默认自动等待回复

群管理

禁言、解禁、踢人、设名片、发公告

文件发送

从 URL 下载文件发送到群/私聊

消息撤回

撤回机器人发送的消息

定时任务

支持 cron 和间隔两种模式的定时唤醒

一键配置

自动检测 NapCat、端口、多 Agent 配置

架构

QQ ←→ NapCat (OneBot v11)
          ↓  WebSocket :3001 / HTTP :3000
    Xadeus-QQ-MCP (Python MCP Server)
          ↓  MCP 协议
    AI Agent (opencode / Cursor / Claude / ...)

快速开始

前置条件

  1. 安装 NapCat.Shell 和 QQ

  2. 配置 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 配置中的 --qq 参数在运行时会被忽略。 正确方式:启动 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 工具一览

消息

工具

说明

send_message

发文本消息,支持分段、等待回复

send_image

发图片

send_voice

发语音

wait_for_reply

等待新消息

上下文

工具

说明

get_recent_context

查看最近消息

batch_get_recent_context

批量查看多目标

screenshot_chat

生成聊天截图(iPhone 深色模式)

compress_context

压缩缓存

唤醒系统

工具

说明

add_wake_rule

添加唤醒规则(群/私聊 + 关键词)

remove_wake_rule

删除唤醒规则

list_wake_rules

查看所有规则

set_wake_pending

锁定/解锁唤醒

set_wake_enabled

启用/禁用规则

set_wake_config

配置窗口标题和快捷键

get_wake_config

查看唤醒配置

diagnose_wake

诊断唤醒状态

群管理

工具

说明

get_group_list

群列表

get_group_member_list

群成员列表

get_group_member_info

成员详情

mute_member

禁言

unmute_member

解禁

kick_member

踢出

set_member_card

设群名片

send_group_notice

发群公告

系统

工具

说明

check_status

检查连接状态

get_friend_list

好友列表

recall_message

撤回消息

send_file

发送文件

add_timer

添加定时任务

remove_timer

删除定时任务

list_timers

查看所有定时任务

已知问题

问题

原因

解决方法

MCP 被杀后无法自启

opencode 有重启退避策略

重启 AI Agent,或 .\quickstart.ps1 -restart

总是有两个 MCP 进程

FastMCP stdio 产生父子进程链

内置命名互斥锁解决重复打字

改 opencode.json 不生效

opencode 启动时缓存命令

重启 opencode,或用 QQ_OVERRIDE 环境变量

唤醒消息出现双倍字符

两个进程同时打字

已修复(Windows 命名互斥锁)

同 QQ 号发消息不唤醒

is_self 过滤器阻挡

已修复(移除 context.py/wake.py 过滤)

匹配规则但不唤醒

唤醒锁 (_pending) 未释放

5 分钟自动解锁,或调用 set_wake_pending(false)

重启助手

.\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 tools
add_timerA
Idempotent

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_ruleA
Idempotent

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_contextA
Read-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_statusA
Read-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_contextA
Destructive

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_pipelineA
Read-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_wakeA
Read-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_listA
Read-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_listA
Read-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_infoA
Read-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_listA
Read-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_contextA
Read-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_configA
Read-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_memberA
DestructiveIdempotent

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_timersA
Read-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_rulesA
Read-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_memberB
Idempotent

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_messageA
DestructiveIdempotent

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_timerA
DestructiveIdempotent

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_ruleA
DestructiveIdempotent

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_chatA
Read-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_noticeA
Idempotent

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_cardA
Idempotent

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_configA
Idempotent

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_enabledA
Idempotent

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_pendingA
Idempotent

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_activationA
Idempotent

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_memberA
Idempotent

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_replyA
Read-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

    A4.1/5.0

    Scored across 33 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    All tools follow a consistent verb_noun snake_case pattern (e.g., add_timer, list_timers, send_message). No mixing of conventions.

    Tool Count3/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      An 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.
      7
      26
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A 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.
      3
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Connects QQ via NapCat OneBot v11 to an Astral Code app-server, exposing MCP tools for sending messages, files, images, and fetching conversation history.
      10
      2
      Apache 2.0