Skip to main content
Glama

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

Inputs: targets (required), limit.

check_statusA

Check QQ login status and NapCat connection status.

Inputs: no named parameters.

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

Inputs: target (required), target_type.

get_group_listA

Get the list of QQ groups the bot has joined.

Inputs: no named parameters.

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

Inputs: target (required), target_type, limit.

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.

Inputs: target (required), image (required), target_type, reply_to.

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

Inputs: target (required), content (required), target_type, reply_to, +2 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    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

    ActivityStale
    ResponsivenessNo recent community issues

    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.
      114
      MIT
    • A
      license
      A
      quality
      C
      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.
      3
      MIT