Amadeus-QQ-MCP
This server provides MCP tools for AI clients to interact with QQ accounts through a NapCatQQ (OneBot v11) bridge, enabling message sending/receiving, context management, and real-time communication with access controls.
Connection & Status: Check QQ login status and NapCat connection health (
check_status), including buffer statistics.Group Management: Retrieve list of groups the bot joined (
get_group_list).Message Reading: Fetch recent buffered messages (
get_recent_context) for a group or friend, with metadata (sender, self-sent, @mention, image URLs). Efficiently batch-fetch for multiple targets (batch_get_recent_context).Message Sending: Send text messages (
send_message) with support for replying to messages, automatic splitting into semantic chunks with typing delays, and control over chunk count. Send base64-encoded images (send_image) with optional reply.Context Compression: Summarize and free buffer space for a target (
compress_context).Real-time Communication: Listen for incoming messages via WebSocket with automatic reconnection.
Access Control & Rate Limiting: Interaction is limited to whitelisted groups and friends, with a sending rate limit of 3 seconds per target.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Amadeus-QQ-MCPSend 'Got it, I'll check the logs now' to group 987654321"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Amadeus-QQ-MCP
MCP Server,通过 NapCatQQ (OneBot v11) 让 AI 客户端收发 QQ 消息。支持群聊和私聊。
功能
6 个 MCP 工具:
check_status、get_group_list、get_recent_context、batch_get_recent_context、send_message、compress_contextWebSocket 实时消息监听 + 自动重连
消息按自然语义分段发送(句号/逗号/破折号等),模拟真人打字节奏
支持 AI 自主控制消息拆分段数(
num_chunks参数,按标点拆分后合并为指定段数)群/好友白名单控制
发送速率限制(3s/目标)
Related MCP server: Xadeus-QQ-MCP
前置条件
已安装并运行的原生 NapCatQQ(OneBot v11)
Python 3.11+
PetGPT 的内置 QQ Connector 会按需管理 uv、Python 和本项目,用户不需要手动安装 Python,也不使用 Docker。独立运行本项目时,可以使用 NapCat 官方提供的 Windows OneKey/Shell、Linux AppImage 或 macOS Installer。
原生 NapCat 快速接入(推荐)
启动原生 NapCat,并在 WebUI 中完成 QQ 扫码登录。
创建仅监听
127.0.0.1的 OneBot HTTP Server(默认端口 3000)。创建仅监听
127.0.0.1的 OneBot WebSocket Server(默认端口 3001)。两个 Server 使用同一个随机 token。
启动 MCP:
uv run qq-agent-mcp --qq 你的QQ号 --access-token 你的OneBot访问令牌PetGPT 会自动完成第 2~5 步,并在注册前验证 Social Agent 依赖的工具契约。
旧版 Docker 快速开始(Windows,可选)
1. 配置 NapCat
.\scripts\setup-windows.ps1交互式引导你完成:
检查并自动启动 Docker Desktop
拉取 NapCat Docker 镜像
输入 QQ 号、设备名称
生成
docker-compose.yml生成 OneBot11 接口配置(HTTP API 端口 3000 + WebSocket 端口 3001)
生成
mcp.json
2. 启动 NapCat
.\scripts\start-docker-windows.ps1首次启动需扫码登录,查看二维码:
docker compose logs -f napcat或访问 WebUI:http://localhost:6099
3. 启动 MCP Server
uv run qq-agent-mcp --qq 你的QQ号4. 配置 MCP 客户端
setup-windows.ps1 已自动生成 mcp.json:
{
"mcpServers": {
"qq-agent": {
"command": "C:/Users/你的用户名/.local/bin/uv.exe",
"args": "run --directory C:/path/to/Amadeus-QQ-MCP qq-agent-mcp --qq 你的QQ号"
}
}
}将 mcp.json 的内容复制到你的 AI 客户端的 MCP 配置中即可。
旧版 Docker 快速开始(Linux,可选)
1. 安装依赖
scripts/install-linux.sh自动安装 Docker、uv,初始化项目配置并安装 Python 依赖。安装完成后需要 source ~/.bashrc 或打开新终端让 uv 命令生效。
2. 配置 NapCat
scripts/setup-linux.sh交互式引导你完成:
拉取 NapCat Docker 镜像
输入 QQ 号、设备名称、UID/GID
生成
docker-compose.yml生成 OneBot11 接口配置(HTTP API 端口 3000 + WebSocket 端口 3001)
3. 启动 NapCat
scripts/start-docker-linux.sh首次启动需扫码登录,查看二维码:
sudo docker compose logs -f napcat设置
ACCOUNT后,配合restart: always和登录态持久化(./napcat/qq-data),可实现掉线后自动重连。仅当登录 token 过期时才需重新扫码。
4. 测试连接
uv run python scripts/test-mcp-linux.py自动从 docker-compose.yml 读取 QQ 号,依次测试:MCP 握手 → 工具列表 → check_status。也可手动指定:
uv run python scripts/test-mcp-linux.py --qq 你的QQ号5. 启动 MCP Server
# 最小参数
uv run qq-agent-mcp --qq 你的QQ号
# 指定监听群和好友
uv run qq-agent-mcp --qq 你的QQ号 --groups 群号1,群号2 --friends 好友QQ1,好友QQ2
# 全部参数
uv run qq-agent-mcp --qq 你的QQ号 \
--napcat-host 127.0.0.1 \
--napcat-port 3000 \
--ws-port 3001 \
--access-token 你的OneBot访问令牌 \
--groups 群号1,群号2 \
--friends 好友QQ1 \
--buffer-size 100 \
--log-level info--access-token 也可以通过 NAPCAT_ACCESS_TOKEN 环境变量提供。建议为
NapCat 的 OneBot HTTP 和 WebSocket 服务配置同一个随机访问令牌,并只监听
本机地址。
6. 配置 MCP 客户端
scripts/setup-linux.sh 已自动在项目根目录生成 mcp.json,默认监听所有群:
{
"mcpServers": {
"qq-agent": {
"command": "/home/你的用户名/.local/bin/uv",
"args": "run --directory /path/to/Amadeus-QQ-MCP qq-agent-mcp --qq 你的QQ号"
}
}
}将 mcp.json 的内容复制到你的 AI 客户端的 MCP 配置中即可。
如需指定监听的群,在 args 中添加 "--groups", "群号1,群号2"。
CLI 参数
参数 | 默认值 | 说明 |
| — | 机器人 QQ 号 |
|
| NapCat HTTP 地址 |
|
| NapCat HTTP 端口 |
|
| NapCat WebSocket 端口 |
| 全部 | 监听的群号(逗号分隔) |
| 无 | 监听的好友 QQ(逗号分隔) |
|
| 每个目标的消息缓冲区大小 |
|
| 日志级别 |
MCP 工具
工具 | 说明 |
| 检查 QQ 登录状态、在线状态、缓冲区统计 |
| 获取已加入的群列表 |
| 获取消息上下文(JSON 格式,含 is_self/is_at_me 标记) |
| 批量查询多个群/好友的消息上下文(最多 2 次 API 调用) |
| 发消息,自动分段+打字延迟。 |
| 手动压缩历史消息为摘要 |
架构
MCP Client (stdio)
↕ JSON-RPC
qq-agent-mcp (Python)
├── HTTP API → NapCat (OneBot v11) → QQ
└── WebSocket ← NapCat (消息事件)
↓
Message Buffer (滑动窗口)目录结构
Amadeus-QQ-MCP/
├── src/qq_agent_mcp/ # MCP Server 源码
├── scripts/ # 辅助脚本
│ ├── install-linux.sh # 一键安装 (Linux)
│ ├── setup-linux.sh # NapCat 配置 (Linux)
│ ├── start-docker-linux.sh # 启动 Docker (Linux)
│ ├── test-mcp-linux.py # MCP 连接测试 (Linux)
│ ├── setup-windows.ps1 # NapCat 配置 (Windows)
│ └── start-docker-windows.ps1 # 启动 Docker (Windows)
├── napcat/ # NapCat Docker 挂载目录
│ ├── config/ # NapCat + OneBot 配置
│ └── qq-data/ # QQ 登录态持久化
├── tests/ # 集成测试
├── docker-compose.sample.yml # Docker Compose 模板
├── mcp.json # MCP 客户端配置(setup 自动生成)
├── pyproject.toml # Python 项目配置
└── README.mdLicense
MIT
Available Tools
7 toolsbatch_get_recent_contextA
Batch query recent message context for multiple targets.
More efficient than calling get_recent_context multiple times: uses at most 2 OneBot API calls (group list + friend list) regardless of how many targets are queried.
Args: targets: List of dicts, each with "target" (ID) and optional "target_type" ("group" or "private", default "group"). Example: [{"target": "123", "target_type": "group"}, {"target": "456", "target_type": "private"}] limit: Number of recent messages per target (default 50).
| Name | Required | Description | Default |
|---|---|---|---|
| targets | Yes | ||
| limit | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It explains the tool uses at most 2 API calls regardless of target count, and lists parameters. It does not explicitly state non-destructiveness, but as a query tool, the behavior is clear and well-described.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a concise purpose line, followed by efficiency note, then parameter details. It is informative but not overly verbose, earning its length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description explains what is queried (recent message context) and the parameters, which is sufficient for a batch query tool. It could mention return format or error handling, but overall complete enough for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain parameters. It thoroughly describes 'targets' as a list of dicts with optional 'target_type' and provides an example, and explains 'limit' as number of recent messages per target. This adds full meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Batch query recent message context for multiple targets,' specifying the verb and resource. It distinguishes itself from the sibling get_recent_context by highlighting the batch nature and efficiency over multiple calls.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states it is 'More efficient than calling get_recent_context multiple times' and provides API call optimization details, guiding when to use this tool instead of the single-target alternative. No exclusions are mentioned, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
check_statusA
Check QQ login status and NapCat connection status.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden of behavioral disclosure. The description does not state that the tool is read-only, has no side effects, or what happens if the statuses are not available. It fails to inform about potential impacts or prerequisites beyond the bare action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence with no unnecessary words. It is front-loaded with the action verb and directly states what is checked, making it efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and no output schema, the description is reasonably complete for a simple status check. However, it could be slightly improved by clarifying the expected output or status values, but overall it provides enough context for basic use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so the description does not need to add parameter information. The baseline score for 0 parameters is 4, and the description does not detract from this since it correctly indicates no input is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool checks 'QQ login status' and 'NapCat connection status', providing a specific verb and two clear resources. Among the sibling tools, which include actions like sending messages or managing group members, this is the only one explicitly for status checking, so it is well-distinguished.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool versus alternatives or when it should not be used. It is implied that it might be used before performing actions that require an active connection, but this is not explicit, leaving the agent with insufficient decision-making context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
compress_contextA
Compress all buffered messages for a target into a summary.
This replaces raw messages with a compressed summary, freeing up the buffer. Use this after reading context when you want to archive old messages.
Args: target: Group ID or friend QQ ID. target_type: "group" (default) or "private".
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes | ||
| target_type | No | group |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states that the tool 'replaces raw messages with a compressed summary, freeing up the buffer,' which clearly conveys the destructive nature and effect. Could be improved by noting irreversibility or return value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with the main purpose in the first line, followed by a behavioral explanation and usage guideline in the second paragraph, then parameter docs. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the tool's purpose, behavior, and parameters adequately. No output schema is present, so return values are not described, but for a compression tool the main effect is clear. It covers the essential information for an agent to decide when to use it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description includes an Args section that explains both parameters: target as 'Group ID or friend QQ ID' and target_type with default 'group'. This adds necessary meaning beyond the bare schema, though ID format could be more specific.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Compress'), resource ('buffered messages'), and scope ('for a target into a summary'). It distinguishes itself from sibling tools like get_recent_context and batch_get_recent_context by focusing on compression, not retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises using this tool 'after reading context when you want to archive old messages.' It provides a clear usage context but does not mention when not to use it or list alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_group_listA
Get the list of QQ groups the bot has joined.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. The description only states 'get', implying a read operation, but lacks details such as whether the list includes all groups, pagination, or any rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no superfluous words. Front-loaded with the action and resource. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with no parameters and no output schema, the description is minimally complete. It tells the agent exactly what the tool retrieves. However, it lacks any usage context or caveats, which would elevate it to a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, and the schema coverage is 100% (empty). The description adds no parameter-level detail beyond the schema, but with zero parameters, the baseline is 4. The description effectively covers the tool's purpose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get the list') and the resource ('QQ groups the bot has joined'). It distinguishes from siblings like get_friend_list or get_group_member_list by specifying groups vs friends or members.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. While the name and description imply it lists groups, there is no explicit context, prerequisites, or exclusions provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_recent_contextA
Get recent message context for a monitored group or whitelisted friend.
Returns all buffered messages (backfill + real-time) without compression. Use compress_context to manually compress when needed. Images are returned as URL strings in each message's image_urls field.
Args: target: Group ID or friend QQ ID. target_type: "group" (default) or "private". limit: Number of recent messages to return (default 200).
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes | ||
| target_type | No | group | |
| limit | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that messages are buffered (backfill+real-time) and returned as URLs in image_urls field. Lacks details on rate limits, authentication, or error behavior, but overall decent for a read-only tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise and well-structured with a clear Args section. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers main behavior (uncompressed, buffered, image URLs) but missing details on error handling, validation, or what happens when target is not monitored. Adequate but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, description fully explains each parameter: target (Group ID or friend QQ), target_type (group/private), limit (default 200). Adds clarity beyond raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it retrieves recent message context for monitored groups or whitelisted friends. Differentiates from sibling 'compress_context' by noting it returns uncompressed messages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly recommends 'compress_context' as an alternative for compression. However, does not clarify when not to use this tool or prerequisites like needing to have the target monitored.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
send_imageA
Send an image to a monitored group or whitelisted friend.
Args: target: Group ID or friend QQ ID. image: Base64-encoded image data (without the base64:// prefix). target_type: "group" (default) or "private". reply_to: Optional message ID to reply to.
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes | ||
| image | Yes | ||
| target_type | No | group | |
| reply_to | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Provides behavioral details (monitored group/whitelisted friend, base64 format without prefix) but no annotations exist. Lacks disclosures on permissions, rate limits, or failure behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences front-load purpose, followed by parameter list. No wasted words, efficient structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers parameters adequately but lacks details on return value, error handling, file size limits, and exact encoding validation. Acceptable for simple tool but gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, description adds essential meaning: target is ID, image base64 encoding, target_type default/options, reply_to optional. Compensates well for missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'send' and resource 'image', and distinguishes from siblings like send_message, send_file, send_voice by specifying image-specific details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage for sending images to groups or friends, but lacks explicit when to use vs alternatives like send_message with image attachment, and no when-not scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
send_messageA
Send a message to a monitored group or whitelisted friend.
Args: target: Group ID or friend QQ ID. content: Text message content. target_type: "group" (default) or "private". reply_to: Optional message ID to reply to. split_content: Whether to split long messages into multiple chunks with typing delay (default True). Set to False to send as a single message without splitting. num_chunks: If set, split the message into exactly this many chunks using natural punctuation boundaries. Overrides split_content. The message is first split by punctuation, then the fine chunks are merged into exactly num_chunks groups (e.g. num_chunks=3 sends exactly 3 messages with typing delays between them).
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes | ||
| content | Yes | ||
| target_type | No | group | |
| reply_to | No | ||
| split_content | No | ||
| num_chunks | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses some behavioral traits like message splitting with typing delays and reply functionality, but doesn't mention authentication needs, rate limits, error conditions, or what happens when sending fails. It adequately describes the core behavior but lacks operational context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear purpose statement followed by detailed parameter explanations. Every sentence adds value, though the parameter explanations could be slightly more concise. The information is appropriately front-loaded with the core purpose first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 6-parameter tool with no annotations and no output schema, the description covers parameter semantics thoroughly but lacks information about return values, error handling, authentication requirements, and operational constraints. It's complete for basic usage but insufficient for robust implementation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Given 0% schema description coverage, the description fully compensates by explaining all 6 parameters in detail. It clarifies target types, optional reply functionality, and sophisticated message splitting behavior including the interaction between split_content and num_chunks. This adds substantial value beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Send a message') and target ('to a monitored group or whitelisted friend'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'send_image' beyond the message type, which prevents a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'send_image' or other communication methods. It mentions target types but doesn't explain when to choose 'group' vs 'private' or prerequisites for sending messages.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
7 tool updates
v0.1.0- First observed
batch_get_recent_context - First observed
check_status - First observed
compress_context - First observed
get_group_list - First observed
get_recent_context - First observed
send_image - First observed
send_message
TDQS
Scored across 7 tools
Each tool has a clearly distinct purpose with no ambiguity: batch_get_recent_context handles multiple targets efficiently, get_recent_context retrieves single-target context, compress_context summarizes and archives, send_message and send_image handle different message types, check_status monitors connectivity, and get_group_list lists groups. The descriptions clearly differentiate overlapping concepts like batch vs single queries and compression vs raw retrieval.
All tools follow a consistent verb_noun pattern with snake_case throughout: batch_get_recent_context, check_status, compress_context, get_group_list, get_recent_context, send_image, and send_message. The naming is predictable and readable, making it easy for agents to understand each tool's function from its name alone.
With 7 tools, this server is well-scoped for QQ/OneBot messaging operations. Each tool earns its place by covering essential functions: status checking, group listing, context retrieval (single and batch), context compression, and message sending (text and image). This count avoids both thin coverage and feature bloat for the domain.
The tool surface provides excellent coverage for core QQ messaging workflows: status monitoring, group discovery, context retrieval/management, and message sending. A minor gap exists in message management (e.g., deleting or editing sent messages), but agents can work effectively with the provided tools for typical bot operations without encountering dead ends.
Maintenance
Related MCP Connectors
MCP server for AI dialogue using various LLM models via AceDataCloud
MCP server for GLM chat completions using Zhipu AI models via AceDataCloud
An MCP server that integrates with Discord to provide AI-powered features.
MCP server for Qwen Image 3 AI image generation
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA WeChat robot server based on the Model Context Protocol that enables AI agents to send and receive messages and manage typing status. It provides tools for QR code login, long-polling message retrieval, and persistent state management across various MCP clients.33 npm108MIT
- AlicenseAqualityBmaintenanceQQ MCP Server with Auto-Wake, message send/receive, group management, file sharing, and timed tasks. Connects via NapCatQQ (OneBot v11). One-click setup with quickstart.ps1.Based on Amadeus-QQ-MCP.333MIT
- FlicenseNot gradedqualityDmaintenanceAn MCP server that enables WorkBuddy to invoke the kimi-code CLI locally via MCP protocol, allowing remote task execution through QQ messages.-
- 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.2MIT