Xadeus-QQ-MCP

Built by a 15-year-old developer, based on Amadeus-QQ-MCP.

QQ MCP (Model Context Protocol) Server — connects to QQ via NapCatQQ (OneBot v11), giving AI agents direct control over QQ (send/receive messages, group management, auto-wake on incoming messages, and more).

Features

Architecture

QQ ←→ NapCat (OneBot v11)
          ↓  WebSocket :3001 / HTTP :3000
    Xadeus-QQ-MCP (Python MCP Server)
          ↓  MCP Protocol
    AI Agent (opencode / Cursor / Claude / ...)

Quick Start

Prerequisites

1. Install NapCat.Shell and QQ
2. Configure NapCat OneBot v11 (WebSocket :3001, HTTP :3000)

One-Click Setup (Recommended)

.\quickstart.ps1 -qq 你的QQ号

Auto-detects NapCat, configures HTTP:3000/WS:3001, creates Python venv, writes QQ_OVERRIDE, generates NapCat start script, sets window wake patterns.

Options:

.\quickstart.ps1 -qq 123456 -windowTitle "OC,opencode,cmd"   # Custom window patterns
.\quickstart.ps1 -configFile config.json                      # Config file mode
.\quickstart.ps1 -restart                                     # Kill stale MCP + wait for recovery

Default -windowTitle: OC,opencode,Administrator,cmd,管理员 (comma-separated substrings, matched case-insensitively against window titles)

Also available via Python:

python setup.py          # Interactive mode
python setup.py --qq YOUR_QQ --fast   # Non-interactive

Manual Setup

git clone https://github.com/mouse114514/Xadeus-QQ-MCP
cd Xadeus-QQ-MCP

# Virtual env
uv venv
uv sync

# Start MCP Server
uv run python -m qq_agent_mcp --qq YOUR_QQ

Configure Your AI Agent

Important: The --qq argument passed by your AI agent config is ignored at runtime. Instead, set QQ_OVERRIDE environment variable before starting your agent:

powershell

Copy

$env:QQ_OVERRIDE = "YOUR_QQ"

Or edit the fallback value in src/qq_agent_mcp/__main__.py:QQ_OVERRIDE.

This works around AI agents that cache the MCP command at startup and ignore subsequent config file changes.

opencode — edit ~/.config/opencode/opencode.json:

{
  "mcp": {
    "qq-agent": {
      "type": "local",
      "command": [
        "C:\\path\\.venv\\Scripts\\python.exe",
        "-m", "qq_agent_mcp",
        "--qq", "YOUR_QQ"
      ],
      "enabled": true,
      "timeout": 120000
    }
  }
}

Cursor / Claude Desktop / Windsurf — edit the respective MCP config file:

{
  "mcpServers": {
    "qq-agent": {
      "command": "C:\\path\\.venv\\Scripts\\python.exe",
      "args": ["-m", "qq_agent_mcp", "--qq", "YOUR_QQ"],
      "enabled": true
    }
  }
}

Or just run python setup.py — it detects all installed agents automatically.

Wake Target Configuration

Use set_wake_config to bind to any AI agent window:

{
  "window_title_patterns": ["opencode", "cursor", "claude"],
  "focus_shortcut": "ctrl+l"
}

Saved to src/qq_agent_mcp/wake_config.json.

MCP Tools

Messaging

Context & History

Wake System

Group Management

System

Known Issues & Workarounds

Restart Helper

.\quickstart.ps1 -restart

Kills stale MCP processes and waits for auto-restart. If the agent doesn't recover, it prompts you to restart manually.

Tech Stack

• Python 3.12+ (httpx, aiohttp, FastMCP)
• NapCat.Shell (QQ + OneBot v11)
• Win32 API (ctypes) — window activation, keyboard simulation

License

Based on Amadeus-QQ-MCP (MIT License).

中文版

Xadeus-QQ-MCP

由一位 15 岁高中生基于 Amadeus-QQ-MCP 深度优化改造。

QQ MCP (Model Context Protocol) Server — 通过 NapCatQQ (OneBot v11) 协议连接 QQ，为 AI Agent 提供直接操控 QQ 的能力（收发消息、管理群聊、自动唤醒等）。

功能亮点

架构

QQ ←→ NapCat (OneBot v11)
          ↓  WebSocket :3001 / HTTP :3000
    Xadeus-QQ-MCP (Python MCP Server)
          ↓  MCP 协议
    AI Agent (opencode / Cursor / Claude / ...)

快速开始

前置条件

1. 安装 NapCat.Shell 和 QQ
2. 配置 NapCat OneBot v11 (WebSocket :3001, HTTP :3000)

一键配置（推荐）

.\quickstart.ps1 -qq 你的QQ号

自动检测 NapCat、配置 HTTP:3000/WS:3001、创建 Python venv、 写入 QQ_OVERRIDE、生成 NapCat 启动脚本、设置窗口唤醒匹配模式。

选项：

.\quickstart.ps1 -qq 123456 -windowTitle "OC,opencode,cmd"   # 自定义窗口匹配模式
.\quickstart.ps1 -configFile config.json                      # 配置文件模式
.\quickstart.ps1 -restart                                     # 杀死残留 MCP + 等待恢复

默认 -windowTitle：OC,opencode,Administrator,cmd,管理员 （逗号分隔，不区分大小写子串匹配窗口标题）

Python 版（功能相同）：

python setup.py                           # 交互模式
python setup.py --qq 你的QQ号 --fast       # 静默模式

手动安装

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