Skip to main content
Glama

Amadeus-QQ-MCP

MCP Server,通过 NapCatQQ (OneBot v11) 让 AI 客户端收发 QQ 消息。支持群聊和私聊。

功能

  • 6 个 MCP 工具check_statusget_group_listget_recent_contextbatch_get_recent_contextsend_messagecompress_context

  • WebSocket 实时消息监听 + 自动重连

  • 消息按自然语义分段发送(句号/逗号/破折号等),模拟真人打字节奏

  • 支持 AI 自主控制消息拆分段数(num_chunks 参数,按标点拆分后合并为指定段数)

  • 群/好友白名单控制

  • 发送速率限制(3s/目标)

Related MCP server: Xadeus-QQ-MCP

前置条件

  • 已安装并运行的原生 NapCatQQ(OneBot v11)

  • Python 3.11+

  • uv

PetGPT 的内置 QQ Connector 会按需管理 uv、Python 和本项目,用户不需要手动安装 Python,也不使用 Docker。独立运行本项目时,可以使用 NapCat 官方提供的 Windows OneKey/Shell、Linux AppImage 或 macOS Installer。

原生 NapCat 快速接入(推荐)

  1. 启动原生 NapCat,并在 WebUI 中完成 QQ 扫码登录。

  2. 创建仅监听 127.0.0.1 的 OneBot HTTP Server(默认端口 3000)。

  3. 创建仅监听 127.0.0.1 的 OneBot WebSocket Server(默认端口 3001)。

  4. 两个 Server 使用同一个随机 token。

  5. 启动 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 (必填)

机器人 QQ 号

--napcat-host

127.0.0.1

NapCat HTTP 地址

--napcat-port

3000

NapCat HTTP 端口

--ws-port

3001

NapCat WebSocket 端口

--groups

全部

监听的群号(逗号分隔)

--friends

监听的好友 QQ(逗号分隔)

--buffer-size

100

每个目标的消息缓冲区大小

--log-level

info

日志级别

MCP 工具

工具

说明

check_status

检查 QQ 登录状态、在线状态、缓冲区统计

get_group_list

获取已加入的群列表

get_recent_context(target, target_type?, limit?)

获取消息上下文(JSON 格式,含 is_self/is_at_me 标记)

batch_get_recent_context(targets, limit?)

批量查询多个群/好友的消息上下文(最多 2 次 API 调用)

send_message(target, content, target_type?, reply_to?, split_content?, num_chunks?)

发消息,自动分段+打字延迟。num_chunks 可指定恰好拆为几段(先按标点拆再合并)

compress_context(target, target_type?)

手动压缩历史消息为摘要

架构

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

License

MIT

Available Tools

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

ParametersJSON Schema
NameRequiredDescriptionDefault
targetsYes
limitNo

TDQS

A4.4/5.0
Behavior4/5

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.

Conciseness4/5

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.

Completeness4/5

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.

Parameters5/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.6/5.0
Behavior2/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines2/5

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

ParametersJSON Schema
NameRequiredDescriptionDefault
targetYes
target_typeNogroup

TDQS

A4.4/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.6/5.0
Behavior2/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines2/5

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

ParametersJSON Schema
NameRequiredDescriptionDefault
targetYes
target_typeNogroup
limitNo

TDQS

A4.1/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness3/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
targetYes
imageYes
target_typeNogroup
reply_toNo

TDQS

A3.9/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness3/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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

ParametersJSON Schema
NameRequiredDescriptionDefault
targetYes
contentYes
target_typeNogroup
reply_toNo
split_contentNo
num_chunksNo

TDQS

A3.5/5.0
Behavior3/5

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.

Conciseness4/5

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.

Completeness3/5

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.

Parameters5/5

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.

Purpose4/5

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.

Usage Guidelines2/5

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.

  1. 7 tool updatesv0.1.0
    • First observedbatch_get_recent_context
    • First observedcheck_status
    • First observedcompress_context
    • First observedget_group_list
    • First observedget_recent_context
    • First observedsend_image
    • First observedsend_message

TDQS

A3.7/5.0

Scored across 7 tools

Disambiguation5/5

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.

Naming Consistency5/5

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.

Tool Count5/5

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.

Completeness4/5

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

ActivitySlowing
ResponsivenessUnresponsive

Related MCP Connectors

Related MCP Servers

  • A
    license
    Not graded
    quality
    D
    maintenance
    A 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 npm
    108
    MIT
  • A
    license
    A
    quality
    B
    maintenance
    QQ 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.
    33
    3
    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.
    2
    MIT