内容
<!-- markdownlint-disable MD033 MD041 MD024 -->
<p align="center">
<img alt="LOGO" src="https://cdn.jsdelivr.net/gh/MaaAssistantArknights/design@main/logo/maa-logo_512x512.png" width="256" height="256" />
</p>
<div align="center">
# MaaMCP
[](https://github.com/MaaXYZ/MaaFramework)
[](https://pypi.org/project/maa-mcp/)
基于 [MaaFramework](https://github.com/MaaXYZ/MaaFramework) 的 MCP 服务器
为 AI 助手提供 Android 设备和 Windows 桌面自动化能力
[English](README_EN.md) | 中文
</div>
---
## 简介
MaaMCP 是一个 MCP 服务器，将 MaaFramework 的强大自动化能力通过标准化的 MCP 接口暴露给 AI 助手（如 Claude）。通过本服务器，AI 助手可以：
- 🤖 **Android 自动化** - 通过 ADB 连接并控制 Android 设备/模拟器
- 🖥️ **Windows 自动化** - 控制 Windows 桌面应用程序
- 🎯 **后台操作** - Windows 上的截图与控制均在后台运行，不占用鼠标键盘，您可以继续使用电脑做其他事情
- 🔗 **多设备协同** - 同时控制多个设备/窗口，实现跨设备自动化
- ⚡ **双模式运行** - 串行模式（同步执行）和流水线模式（后台持续截图），适应不同场景需求
- 👁️ **智能识别** - 使用 OCR 识别屏幕文字内容
- 🎯 **精准操作** - 执行点击、滑动、文本输入、按键等操作
- 📸 **屏幕截图** - 获取实时屏幕截图进行视觉分析
Talk is cheap, 请看: **[🎞️ Bilibili 视频演示](https://www.bilibili.com/video/BV1eGmhBaEZz/)**
## 功能特性
### 🔍 设备发现与连接
- `find_adb_device_list` - 扫描可用的 ADB 设备
- `find_window_list` - 扫描可用的 Windows 窗口
- `connect_adb_device` - 连接到 Android 设备
- `connect_window` - 连接到 Windows 窗口
### 👀 屏幕识别
- `ocr` - 光学字符识别（高效，推荐优先使用）
- `screencap` - 屏幕截图（按需使用，token 开销大）
#### 截图与坐标约定
Win32 和 ADB 连接默认使用 `target_short_side=720`，保持画面比例。OCR 的 `region`、
返回框、点击、滑动和 Pipeline 均使用该控制器的完整截图坐标，不一定是设备物理坐标。
`screencap` 默认 `resolution=None`，不再额外缩放，整图坐标可直接用于操作。
连接时可传 `target_short_side=1080` 等正整数，或传 `None` 使用原尺寸。该选项会改变
整个控制器的坐标基准，模板和 Pipeline ROI 必须使用匹配的尺度；现有 720p 资源应保留
默认连接设置。依赖旧版 Win32 1080p 坐标的调用方可显式选择 `1080`。
`screencap` 默认仍返回路径字符串。裁图或显式设置 `resolution` 后需要定位操作时，
传入 `include_metadata=True`，返回以下信息：
| 字段 | 含义 |
| --- | --- |
| `path` | 图像绝对路径，也可传给 `save_captured_image` |
| `controller_id` / `coordinate_system` | 所属控制器及坐标空间（`controller`） |
| `coordinate_size` | 控制器完整截图 `[宽, 高]` |
| `image_size` | 保存图像 `[宽, 高]` |
| `image_to_controller.scale` | 图像到控制器的 `[sx, sy]` 比例 |
| `image_to_controller.offset` | 实际裁剪原点在控制器空间中的 `[ox, oy]` |
图中点 `(u, v)` 应换算为 `(round(u*sx+ox), round(v*sy+oy))` 再用于点击。
变换包含实际缩放尺寸、取整和裁剪边界修正，只对应本次截图；窗口大小或布局变化后应重新截图。
显式 `resolution` 只影响保存图像，不改变控制器坐标，也不能恢复之前下采样丢失的细节。
### 🎮 设备控制
- `click` - 点击指定坐标（支持多触点/鼠标按键选择、长按）
- Windows 上支持指定鼠标按键：左键、右键、中键
- `double_click` - 双击指定坐标
- `swipe` - 滑动手势（Android 设备滚动/翻页优先使用）
- `input_text` - 输入文本
- `click_key` - 按键操作（支持长按）
- Android 上可模拟系统按键：返回键(4)、Home键(3)、菜单键(82)、音量键等
- Windows 上支持虚拟按键码：回车(13)、ESC(27)、方向键等
- `keyboard_shortcut` - 键盘快捷键
- 支持组合键：Ctrl+C、Ctrl+V、Alt+Tab 等
- `scroll` - 鼠标滚轮（仅 Windows）
### ⚡ 流水线模式（多线程后台监控）
- `start_pipeline` - 启动后台监控流水线，持续截图并缓存图片路径
- `stop_pipeline` - 停止流水线
- `get_new_messages` - 获取流水线缓存的新截图路径
- `get_pipeline_status` - 获取流水线运行状态
### 📝 Pipeline 生成与运行
- `get_pipeline_protocol` - 获取 Pipeline 协议文档
- `save_pipeline` - 保存 Pipeline JSON 到文件（支持新建和更新）
- `load_pipeline` - 读取已有的 Pipeline 文件
- `run_pipeline` - 运行 Pipeline 并返回执行结果（支持单/多文件、Custom action agent 自动启动、单次 `pipeline_override` 参数覆盖、工具侧 `timeout_seconds` 超时）
### 🛑 Pipeline 终止
- `stop_pipeline` - 原子地停止 Tasker / Agent 子进程 / OCR 循环，杜绝后台孤儿进程
## 快速开始
### 安装方式
#### 方式一：通过 uv 安装（推荐）
需要先安装 [uv](https://docs.astral.sh/uv/#installation)
```bash
uvx maa-mcp
```
#### 方式二：通过 pip 安装
```bash
pip install maa-mcp
```
#### 方式三：从源码安装
1. **克隆仓库**
```bash
git clone https://github.com/MistEO/MaaMCP.git
cd MaaMCP
```
2. **安装 Python 依赖**
```bash
pip install -e .
```
### 运行方式
MaaMCP 提供两种运行模式：
#### 标准服务器（串行模式）
传统的同步执行方式，适合简单任务：
```bash
# 已安装包的情况
maa-mcp
# 从源码开发运行
python -m maa_mcp
```
#### 流水线服务器（多线程后台监控）
多线程异步执行方式，适合需要高频屏幕监控的实时自动化任务：
```bash
# 已安装包的情况
maa-mcp-server
# 从源码开发运行
python -m maa_mcp.pipeline_server
```
两种服务器的功能完全一致，均支持串行模式和流水线模式的自动化流程。区别在于流水线服务器内部使用独立的后台线程持续采集屏幕截图，可根据任务需求灵活选择。
### 配置客户端
在 Cursor 等软件中，添加 MCP 服务器：
```json
{
"mcpServers": {
"MaaMCP": {
"command": "maa-mcp"
}
}
}
```
或
在 Cherry Studio 等软件中，添加 MCP 命令：
```shell
uvx maa-mcp
```
## 使用示例
配置完成后，可以这样使用：
**Android 自动化示例：**
```text
请用 MaaMCP 工具帮我连接 Android 设备，打开美团帮我点一份外卖，我想吃中餐，一人份，20 元左右的
```
**Windows 自动化示例：**
```text
请用 MaaMCP 工具，看看我现在这页 PPT 怎么加一个旋转特效，操作给我看下
```
**Pipeline 生成示例：**
```text
请用 MaaMCP 工具连接我的设备，帮我打开设置，进入显示设置，调整亮度到 50%。
操作完成后，帮我生成这个流程的 Pipeline JSON，以便后续可以直接运行。
```
MaaMCP 会自动：
1. 扫描可用设备/窗口
2. 建立连接
3. 自动下载并加载 OCR 资源
4. 执行识别和操作任务
## 工作流程
MaaMCP 遵循简洁的操作流程，支持多设备/多窗口协同工作，并提供两种运行模式：
```mermaid
graph LR
A[扫描设备] --> B[建立连接]
B --> C1[串行模式]
B --> C2[流水线模式]
C1 --> D[执行自动化操作]
C2 --> D
```
1. **扫描** - 使用 `find_adb_device_list` 或 `find_window_list`
2. **连接** - 使用 `connect_adb_device` 或 `connect_window`（可连接多个设备/窗口，获得多个控制器 ID）
3. **操作** - 通过指定不同的控制器 ID，对多个设备/窗口执行 OCR、点击、滑动等自动化操作
### 双模式运行
MaaMCP 支持两种运行模式，可根据任务需求灵活选择：
#### 串行模式（默认）
传统的同步执行方式，一个指令完成后再执行下一个：
```
OCR识别 → 分析结果 → 执行操作 → OCR识别 → ...
```
**适用场景**：简单任务、对实时性要求不高的场景
#### 流水线模式（多线程后台监控）
多线程异步执行方式，后台持续采集屏幕信息，主线程专注于决策和操作：
```mermaid
graph LR
subgraph 后台线程
S1[持续截图] --> S2[缓存图片路径]
S2 --> S3[推送到消息队列]
S3 --> S1
end
subgraph 主线程
M1[获取截图路径] --> M2[视觉分析]
M2 --> M3[决定是否OCR]
M3 --> M4[执行操作]
M4 --> M1
end
```
**工作流程**：
1. **启动流水线** - 调用 `start_pipeline(controller_id)` 启动后台监控
2. **获取截图** - 调用 `get_pipeline_status()` 检查状态，`get_new_messages()` 获取截图路径
3. **分析执行** - 读取图片进行视觉分析，根据需要调用 OCR，执行点击等操作
4. **停止流水线** - 任务完成后调用 `stop_pipeline()` 释放资源
**优势**：
- 后台持续截图，AI 可直接查看完整画面进行决策
- AI 可根据图片内容自行决定是否需要 OCR、具体 OCR 哪个区域
- 支持高频屏幕监控，不错过任何界面变化
- 适合需要快速响应的实时自动化任务
- 消息队列机制，支持异步处理
**使用示例**：
```text
请用 MaaMCP 工具连接我的设备，使用流水线模式监控屏幕，当出现特定弹窗时自动点击确认。
```
## Pipeline 生成功能
MaaMCP 支持让 AI 将执行过的操作转换为 [MaaFramework Pipeline](https://maafw.xyz/docs/3.1-PipelineProtocol) JSON 格式，实现**一次操作，无限复用**。
### 工作原理
```mermaid
graph LR
A[AI 执行操作] --> B[操作完成]
B --> C[AI 阅读 Pipeline 文档]
C --> D[AI 智能生成 Pipeline]
D --> E[保存 JSON 文件]
E --> F[运行验证]
F --> G{是否成功?}
G -->|是| H[完成]
G -->|否| I[分析失败原因]
I --> J[修改 Pipeline]
J --> F
```
1. **执行操作** - AI 正常执行 OCR、点击、滑动等自动化操作
2. **获取文档** - 调用 `get_pipeline_protocol` 获取 Pipeline 协议规范
3. **智能生成** - AI 根据文档规范，将**有效操作**转换为 Pipeline JSON
4. **保存文件** - 调用 `save_pipeline` 保存生成的 Pipeline
5. **运行验证** - 调用 `run_pipeline` 验证 Pipeline 是否正常运行
6. **迭代优化** - 根据运行结果分析失败原因，修改 Pipeline 直到成功
### 智能生成的优势
与机械录制不同，AI 智能生成具有以下优势：
- **只保留成功路径**：如果操作过程中尝试了多条路径（如先进入 A 菜单没找到，返回后又进入 B 菜单才找到），AI 会只保留最终成功的路径，去掉失败的尝试
- **理解操作意图**：AI 能够理解每个操作的目的，生成语义清晰的节点名称
- **优化识别条件**：根据 OCR 结果智能设置识别区域和匹配条件
- **验证与迭代**：通过运行验证发现问题，自动修复并增强鲁棒性
### 验证与迭代优化
Pipeline 生成后，AI 会自动进行验证和优化：
1. **运行验证** - 执行 Pipeline 检查是否成功
2. **失败分析** - 如果失败，分析具体哪个节点出错及原因
3. **智能修复** - 常见优化手段：
- 增加备选识别节点（在 next 列表中添加多个候选）
- 放宽 OCR 匹配条件（使用正则表达式或部分匹配）
- 调整 roi 识别区域
- 增加等待时间（post_delay）
- 添加中间状态检测节点
4. **重新验证** - 修改后再次运行，直到稳定成功
如果发现 Pipeline 逻辑本身有问题，AI 还可以重新执行自动化操作，结合新旧经验生成更完善的 Pipeline。
### 示例输出
```json
{
"开始任务": {
"recognition": "DirectHit",
"action": "DoNothing",
"next": ["点击设置"]
},
"点击设置": {
"recognition": "OCR",
"expected": "设置",
"action": "Click",
"next": ["进入显示"]
},
"进入显示": {
"recognition": "OCR",
"expected": "显示",
"action": "Click",
"next": ["调整亮度"]
},
"调整亮度": {
"recognition": "OCR",
"expected": "亮度",
"action": "Swipe",
"begin": [200, 500],
"end": [400, 500],
"duration": 200
}
}
```
### 多文件 Pipeline 加载
`run_pipeline` 和 `load_pipeline` 接受 `str` 或 `list[str]`：
```python
# 单文件
run_pipeline(controller_id, "main.json")
# 单文件 list（与 str 等价）
run_pipeline(controller_id, ["main.json"])
# 多文件：一个文件中的节点可以引用另一个文件的节点
run_pipeline(
controller_id,
["main.json", "battle.json", "login.json"],
on_conflict="strict", # 默认 strict：节点名冲突立即报错
)
```
合并语义：
- 所有文件的节点被合并到 Resource 的同一全局节点表
- 节点 `next` 引用在合并后的命名空间内解析（支持跨文件引用）
- 节点冲突默认 `strict` 模式（不写入 Resource）；可设为 `overwrite` 允许后文件覆盖
- 加载是原子的：所有预校验通过后才写入 Resource
- 节点驻留：已加载的节点持续驻留，切换 pipeline 集时调用 `clear_pipeline_resources()` 重置
### 单节点快速验证（pipeline_override + timeout_seconds）
调试单个节点时，不必反复改 pipeline 文件，也不必忍受整屏识别慢扫或无限阻塞：
```python
run_pipeline(
controller_id,
"main.json",
entry="点击设置", # 只从被测节点进入
start_agent=False, # 只测识别，不拉起 CustomAction 链
pipeline_override={ # 单次生效：不写文件、不污染 Resource
"点击设置": {"roi": [520, 20, 200, 80], "timeout": 3000}
},
timeout_seconds=10, # 工具侧超时：超过 10s 自动 post_stop
)
```
- `pipeline_override` 与 interface.json 的同名机制一致：**按字段合并**到已加载节点，
也可覆盖 `expected` / `threshold` / `enabled` 等任意字段；ROI 越准单次识别越快
- 超时返回 `status="timeout"` + 超时前已执行的节点详情，方便定位挂在哪个节点
- `benchmark_node` 同样支持 `pipeline_override`，调参循环免改文件
## 注意事项
📌 **Windows 自动化限制**：
- 部分游戏或应用的反作弊机制可能会拦截后台控制操作
- 若目标应用以管理员权限运行，MaaMCP 也需要以管理员权限启动
- 不支持对最小化的窗口进行操作，请保持目标窗口在非最小化状态
- 若默认的后台截图/输入方式不可用（如截图为空、操作无响应），AI 助手可能会尝试切换到前台方式，届时会占用鼠标键盘
## 平台支持
| 功能 | Windows | macOS | Linux |
|---|---|---|---|
| MCP 服务器（`maa-mcp`） | 支持 | 支持 | 支持 |
| 流水线模式（`maa-mcp-server`） | 支持 | 支持 | 支持 |
| `find_adb_device_list` / `connect_adb_device` | 支持 | 支持 | 支持 |
| `find_window_list` / `connect_window` | 支持 | 不支持 | 不支持 |
| 后台截图 / 鼠标 / 键盘 | 支持 | 不支持 | 不支持 |
**Linux 说明**：
- Linux 下可正常使用 ADB 方式控制 Android 设备。
- **不支持** Win32 桌面窗口控制 —— `find_window_list()` / `connect_window()` 在非 Windows 平台会返回 `None` 或抛错。
- 若在 Linux 下看到 ANSI 颜色转义码（如 `[31m...`）混入 MCP stdio 流，是与部分 MCP 客户端的已知交互问题。日志仍然会写入 `~/.local/share/MaaMCP/logs/`，不受影响。
## 常见问题
## 常见问题
### OCR 识别失败，报错 "Failed to load det or rec" 或提示资源不存在
首次使用时，会自动下载 OCR 模型文件。但可能出现下载失败等情况，请检查数据目录：
- Windows: `C:\Users\<用户名>\AppData\Local\MaaMCP\resource\model\ocr\`
- macOS: `~/Library/Application Support/MaaMCP/resource/model/ocr/`
- Linux: `~/.local/share/MaaMCP/resource/model/ocr/`
1. 检查上述目录中是否有模型文件（`det.onnx`, `rec.onnx`, `keys.txt`）
2. 检查 `model/download.log` 中是否出现资源下载异常
3. 手动执行 `python -c "from maa_mcp.download import download_and_extract_ocr; download_and_extract_ocr()"` 再次尝试下载
### LM Studio 提示 `'maa-mcp' 不是内部或外部命令`
在 LM Studio 中配置 MCP 服务器时，需要 `maa-mcp` 可执行文件在 `PATH` 上。Windows 下 `pip install` 默认把脚本装到 `<Python 安装目录>\Scripts\`（例如 `C:\Users\<用户名>\AppData\Local\Programs\Python\Python310\Scripts\`），这个目录通常不在 `PATH` 中。修复：
```powershell
# 把 Scripts 目录加到用户 PATH（永久）
setx PATH "%PATH%;%LOCALAPPDATA%\Programs\Python\Python310\Scripts"
```
然后重启 LM Studio。验证：新开一个终端执行 `where maa-mcp` 应该返回脚本路径。详见 #6。
### 关于 ISSUE
提交问题时，请提供日志文件，日志文件路径如下：
- Windows: `C:\Users\<用户名>\AppData\Local\MaaMCP\debug\maa.log`
- macOS: `~/Library/Application Support/MaaMCP/debug/maa.log`
- Linux: `~/.local/share/MaaMCP/debug/maa.log`
## 许可证
本项目采用 [GNU AGPL v3](LICENSE) 许可证。
## 致谢
- **[MaaFramework](https://github.com/MaaXYZ/MaaFramework)** - 提供强大的自动化框架
- **[FastMCP](https://github.com/jlowin/fastmcp)** - 简化 MCP 服务器开发
- **[Model Context Protocol](https://modelcontextprotocol.io/)** - 定义 AI 工具集成标准
连接信息
猜你喜欢
暂无推荐服务器