Amadeus QQ

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/目标）

前置条件

• 已安装并运行的原生 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