# QQ MCP Server

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

## ⚙️ 环境要求

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

## 📦 安装

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

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

### 方式二：手动安装

```bash
# 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