QQ MCP Server

通过 Claude Code 自动发送 QQ 消息的 MCP 插件。基于 Windows UI 自动化（pywinauto），无需 QQ Bot API。

⚙️ 环境要求

项目	要求
操作系统	Windows 10 / 11（macOS / Linux 不支持）
QQ	桌面版已安装并保持登录状态
Python	>= 3.10

📦 安装

方式一：Claude Code 插件安装（推荐）

# 从 GitHub 安装
claude plugins install github.com/<your-username>/qq-mcp-plugin

方式二：手动安装

# 1. 克隆仓库
git clone https://github.com/<your-username>/qq-mcp-plugin.git
cd qq-mcp-plugin

# 2. 安装依赖
pip install -r requirements.txt

# 3. 注册到 Claude Code
claude mcp add qq -- python "C:/path/to/qq-mcp-plugin/server.py"

🛠️ 可用工具

qq_send_message

发送消息给 QQ 好友。

参数	类型	说明
friend	string	QQ 好友昵称（支持模糊匹配）
message	string	消息内容

qq_check_status

检查 QQ 是否在线、自动化是否可用。

🔧 工作原理

Claude Code → MCP stdio → server.py
                              │
                    ┌─────────┴─────────┐
                    │  pywinauto (UIA)  │
                    │  定位 QQ 主窗口    │
                    └─────────┬─────────┘
                              │
              ┌───────────────┴───────────────┐
              │  Ctrl+F → 搜索好友 → Enter    │
              │  Ctrl+V → 粘贴消息 → Enter    │
              └───────────────────────────────┘

关键提示： QQ 窗口必须保持打开且可见，不能被最小化到系统托盘。发送期间请勿操作键盘鼠标，避免干扰自动化流程。

🐛 常见问题

Q: 提示 "QQ 窗口未找到"？

• 确认 QQ 已登录且主窗口可见
• 检查窗口标题是否为 "QQ"（某些修改版 QQ 标题不同）

Q: 消息发给了错误的人？

• 昵称使用模糊匹配，若有多人昵称相似可能匹配到第一人
• 建议使用更精确的昵称

Q: 发送失败 / 卡住？

• 增大 server.py 中 time.sleep() 的等待时间（电脑响应慢时）
• 确保没有其他窗口抢占焦点

📄 License

MIT