How do I use Amadeus-QQ-MCP?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Amadeus-QQ-MCP Send '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 消息。支持群聊和私聊。

功能

5 个 MCP 工具：check_status、get_group_list、get_recent_context、send_message、compress_context
WebSocket 实时消息监听 + 自动重连
消息按自然语义分段发送（句号/逗号/破折号等），模拟真人打字节奏
群/好友白名单控制
发送速率限制（3s/目标）

前置条件

Docker
Python 3.11+
uv

运行

0. 安装 Docker 和 NapCat

安装 Docker：

# macOS — 安装 Docker Desktop
brew install --cask docker

# Ubuntu
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER   # 免 sudo 运行 docker
# 重新登录终端生效

安装 NapCat：

本项目使用 NapCatQQ 的 Docker 镜像作为 QQ 协议端。项目的 docker-compose.yml 已配置好镜像，首次运行 docker compose up -d 时会自动拉取，无需手动安装。

1. 启动 NapCat

docker compose up -d

首次启动需扫码登录，查看二维码：

docker compose logs -f napcat

Ubuntu 服务器：需设置 UID/GID 匹配宿主用户
NAPCAT_UID=1000 NAPCAT_GID=1000 docker compose up -d
macOS 默认值 (501:20) 无需设置。

登录后建议在 napcat/config/webui.json 中设置 "autoLoginAccount": "你的QQ号"，避免重启后重新扫码。

2. 安装依赖 & 启动 MCP Server

# 安装依赖
uv sync

# 启动（最小参数）
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 \
  --groups 群号1,群号2 \
  --friends 好友QQ1 \
  --buffer-size 100 \
  --log-level info

3. 配置 MCP 客户端

在 AI 客户端（PetGPT、Claude Desktop 等）中添加：

{
  "name": "QQ Agent",
  "transport": "stdio",
  "command": "uv",
  "args": [
    "run", "--directory", "/path/to/qq-mcp",
    "qq-agent-mcp",
    "--qq", "你的QQ号",
    "--groups", "群号1,群号2"
  ]
}

或全局安装后直接用：

uv tool install /path/to/qq-mcp

{
  "name": "QQ Agent",
  "transport": "stdio",
  "command": "qq-agent-mcp",
  "args": ["--qq", "你的QQ号", "--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 标记）
`send_message(target, content, target_type?, reply_to?)`	发消息，自动分段+打字延迟
`compress_context(target, target_type?)`	手动压缩历史消息为摘要

架构

MCP Client (stdio)
  ↕ JSON-RPC
qq-agent-mcp (Python)
  ├── HTTP API → NapCat (OneBot v11) → QQ
  └── WebSocket ← NapCat (消息事件)
       ↓
  Message Buffer (滑动窗口)

目录结构

qq-mcp/
├── src/qq_agent_mcp/    # MCP Server 源码
├── napcat/              # NapCat Docker 挂载目录（见 napcat/README.md）
├── docker-compose.yml   # NapCat 容器配置
├── pyproject.toml       # Python 项目配置
└── test_mcp.py          # 集成测试