内容
# Xadeus-QQ-MCP
> 由一位 15 岁高中生基于 [Amadeus-QQ-MCP](https://github.com/Sakura325/Amadeus-QQ-MCP) 深度优化改造。
[](https://glama.ai/mcp/servers/mouse114514/Xadeus-QQ-MCP)
QQ MCP (Model Context Protocol) Server — 通过 NapCatQQ (OneBot v11) 协议连接 QQ，为 AI Agent 提供直接操控 QQ 的能力（收发消息、管理群聊、自动唤醒等）。
[]()
[]()
---
## 功能亮点
| 功能 | 说明 |
|------|------|
| **自动唤醒** | QQ 消息匹配规则时自动激活 AI Agent 窗口。<br>**跨平台** — Windows (keybd_event)、macOS (osascript+pbcopy)、Linux (xdotool+xclip)。支持任意客户端 — opencode、Cursor、Claude Desktop、Windsurf，通过 `set_wake_config` 配置窗口标题即可 |
| **Pending 防重复锁** | 唤醒后自动上锁，防止重复唤醒。Agent 干完活后手动解锁 |
| **规则持久化** | 唤醒规则自动保存到 `wake_rules.json`，重启后自动加载 |
| **`wait_for_reply` 一体化** | `send_message` 默认自动等待回复 |
| **群管理** | 禁言、解禁、踢人、设名片、发公告 |
| **文件发送** | 从 URL 下载文件发送到群/私聊 |
| **消息撤回** | 撤回机器人发送的消息 |
| **定时任务** | 支持 cron 和间隔两种模式的定时唤醒 |
| **一键配置** | 自动检测 NapCat、端口、多 Agent 配置 |
## 架构
```
QQ ←→ NapCat (OneBot v11)
↓ WebSocket :3001 / HTTP :3000
Xadeus-QQ-MCP (Python MCP Server)
↓ MCP 协议
AI Agent (opencode / Cursor / Claude / ...)
```
## 快速开始
### 前置条件
1. 安装 [NapCat.Shell](https://github.com/NapNeko/NapCatQQ) 和 QQ
2. 配置 NapCat OneBot v11 (WebSocket :3001, HTTP :3000)
### 一键配置（推荐）
```powershell
.\quickstart.ps1 -qq 你的QQ号
```
自动检测 NapCat、配置 HTTP:3000/WS:3001、创建 Python venv、
写入 QQ_OVERRIDE、生成 NapCat 启动脚本、设置窗口唤醒匹配模式。
选项：
```powershell
.\quickstart.ps1 -qq 123456 -windowTitle "OC,opencode,cmd" # 自定义窗口匹配模式
.\quickstart.ps1 -configFile config.json # 配置文件模式
.\quickstart.ps1 -restart # 杀死残留 MCP + 等待恢复
```
默认 `-windowTitle`：`OC,opencode,Administrator,cmd,管理员`
（逗号分隔，不区分大小写子串匹配窗口标题）
Python 版（功能相同）：
```bash
python setup.py # 交互模式
python setup.py --qq 你的QQ号 --fast # 静默模式
```
### 手动安装
```bash
git clone https://github.com/mouse114514/Xadeus-QQ-MCP
cd Xadeus-QQ-MCP
# 虚拟环境
uv venv
uv sync
# 启动 MCP Server
uv run python -m qq_agent_mcp --qq 你的QQ号
```
### 配置 AI Agent
> **重要**：AI Agent 配置中的 `--qq` 参数在运行时**会被忽略**。<br>正确方式：启动 Agent 前设置环境变量：
> ```powershell
> $env:QQ_OVERRIDE = "你的QQ号"
> ```
> 或直接修改 `src/qq_agent_mcp/__main__.py:QQ_OVERRIDE` 的默认值。<br>
> 这样做是为了绕过 AI Agent 缓存 MCP 命令的问题——<br>Agent 只在启动时读取一次配置，改配置文件不生效。
**opencode** — 编辑 `~/.config/opencode/opencode.json`:
```json
{
"mcp": {
"qq-agent": {
"type": "local",
"command": [
"C:\\path\\.venv\\Scripts\\python.exe",
"-m", "qq_agent_mcp",
"--qq", "你的QQ号"
],
"enabled": true,
"timeout": 120000
}
}
}
```
**Cursor / Claude Desktop / Windsurf** — 编辑对应 MCP 配置文件:
```json
{
"mcpServers": {
"qq-agent": {
"command": "C:\\path\\.venv\\Scripts\\python.exe",
"args": ["-m", "qq_agent_mcp", "--qq", "你的QQ号"],
"enabled": true
}
}
}
```
*运行 `python setup.py` 可自动检测并配置所有已安装的 Agent。*
### 唤醒目标配置
通过 `set_wake_config` 配置窗口标题，即可绑定到任意 AI Agent：
```json
{
"window_title_patterns": ["opencode", "cursor", "claude"],
"focus_shortcut": "ctrl+l"
}
```
配置文件保存在 `src/qq_agent_mcp/wake_config.json`。
## MCP 工具一览
### 消息
| 工具 | 说明 |
|------|------|
| `send_message` | 发文本消息，支持分段、等待回复 |
| `send_image` | 发图片 |
| `send_voice` | 发语音 |
| `wait_for_reply` | 等待新消息 |
### 上下文
| 工具 | 说明 |
|------|------|
| `get_recent_context` | 查看最近消息 |
| `batch_get_recent_context` | 批量查看多目标 |
| `screenshot_chat` | 生成聊天截图（iPhone 深色模式） |
| `compress_context` | 压缩缓存 |
### 唤醒系统
| 工具 | 说明 |
|------|------|
| `add_wake_rule` | 添加唤醒规则（群/私聊 + 关键词） |
| `remove_wake_rule` | 删除唤醒规则 |
| `list_wake_rules` | 查看所有规则 |
| `set_wake_pending` | 锁定/解锁唤醒 |
| `set_wake_enabled` | 启用/禁用规则 |
| `set_wake_config` | 配置窗口标题和快捷键 |
| `get_wake_config` | 查看唤醒配置 |
| `diagnose_wake` | 诊断唤醒状态 |
### 群管理
| 工具 | 说明 |
|------|------|
| `get_group_list` | 群列表 |
| `get_group_member_list` | 群成员列表 |
| `get_group_member_info` | 成员详情 |
| `mute_member` | 禁言 |
| `unmute_member` | 解禁 |
| `kick_member` | 踢出 |
| `set_member_card` | 设群名片 |
| `send_group_notice` | 发群公告 |
### 系统
| 工具 | 说明 |
|------|------|
| `check_status` | 检查连接状态 |
| `get_friend_list` | 好友列表 |
| `recall_message` | 撤回消息 |
| `send_file` | 发送文件 |
| `add_timer` | 添加定时任务 |
| `remove_timer` | 删除定时任务 |
| `list_timers` | 查看所有定时任务 |
## 已知问题
| 问题 | 原因 | 解决方法 |
|------|------|----------|
| **MCP 被杀后无法自启** | opencode 有重启退避策略 | 重启 AI Agent，或 `.\quickstart.ps1 -restart` |
| **总是有两个 MCP 进程** | FastMCP stdio 产生父子进程链 | 内置命名互斥锁解决重复打字 |
| **改 opencode.json 不生效** | opencode 启动时缓存命令 | 重启 opencode，或用 `QQ_OVERRIDE` 环境变量 |
| **唤醒消息出现双倍字符** | 两个进程同时打字 | 已修复（Windows 命名互斥锁） |
| **同 QQ 号发消息不唤醒** | `is_self` 过滤器阻挡 | 已修复（移除 context.py/wake.py 过滤） |
| **匹配规则但不唤醒** | 唤醒锁 (`_pending`) 未释放 | 5 分钟自动解锁，或调用 `set_wake_pending(false)` |
### 重启助手
```powershell
.\quickstart.ps1 -restart
```
杀死残留 MCP 进程并等待自动重启。如果 Agent 不自动恢复，会提示你手动重启。
## 技术栈
- Python 3.12+ (httpx, aiohttp, FastMCP)
- NapCat.Shell (QQ + OneBot v11)
- Win32 API (ctypes) — 窗口激活、键盘模拟
## 授权
基于 Amadeus-QQ-MCP (MIT License) 改造。
