Skip to main content
Glama
README.md
# NoADB Emu MCP(无 ADB 模拟器控制桥)

一个运行在 Windows 本机的 MCP 工具,让支持图片输入的 Agent 不通过 ADB 操作雷电和 MuMu 模拟器:先查看截图,再执行点击、滑动等操作并检查新画面。本项目提供的是控制能力,不包含游戏任务脚本;具体任务由调用方决定。

## 项目特点与优点

- **不依赖 ADB 控制链路**:本项目使用模拟器安装目录中的原生接口获取截图;雷电通过 Windows 后台窗口消息输入,MuMu 使用其原生输入接口。无需为本项目建立 ADB 连接,也不向 Android 内安装触控组件。
- **适合 Agent 看图操作**:以 MCP 图片返回真实画面,支持裁剪、缩小;坐标输入引用截图编号,由控制器换算坐标并拒绝无效编号。
- **后台使用更方便**:截图和输入不移动真实鼠标,也不主动切换前台焦点;启动模拟器时,其自身仍可能显示窗口。其他窗口遮挡的场景已有实测,最小化、锁屏等情况不能一概推断可用。
- **管理与操作集中**:可查询实例、启动、关闭或重启指定实例,并提供截图、点击、长按、滑动、按键与取消;MuMu 还支持 UTF-8 文本输入。
- **多实例与异常处理**:同一服务内,同一实例的操作按顺序执行,不同实例可并行;原生调用在独立工作进程中运行,状态不明时拒绝输入和启停,避免盲目重复操作。
- **本机集成**:通过 stdio 接入支持 MCP 的客户端,不监听网络端口;依赖准备完成后,本工具的控制流程可以离线执行。

## 功能支持

| 功能 | 雷电模拟器 | MuMu 模拟器 |
| --- | --- | --- |
| 实例查询、启动、关闭、重启 | 支持 | 支持 |
| 截图、裁剪、缩小 | 支持 | 支持 |
| 点击、双击、长按、滑动、取消 | 支持 | 支持 |
| 按键 | 主页、最近任务 | 返回、主页、最近任务、回车、音量增减 |
| 文本输入 | 暂不支持,接口会明确拒绝 | 支持 UTF-8 文本 |

具体版本和验证情况见 [STATE.md](STATE.md)。工具返回的 `input_sent` 只表示输入已发出,不表示应用中的任务已经成功;已发出的动作不能撤销,仍需检查画面。

## 与 ADB 方式的区别

| 比较项 | 本项目 | 使用 ADB 的方案 |
| --- | --- | --- |
| 控制路径 | 雷电和 MuMu 的原生接口,以及雷电的 Windows 后台窗口消息;本项目不调用 ADB | 通过 ADB 与 Android 设备或模拟器通信;具体实现取决于所用工具 |
| 配置重点 | 需要 Windows、受支持的模拟器及其安装目录中的接口 | 需要可用的 ADB 和设备连接;具体配置取决于设备及工具 |
| 操作范围 | 聚焦实例管理、截图和画面交互;按键、文本能力因模拟器而异 | 可用于真实设备和模拟器,通常还覆盖 shell、安装应用、文件传输等;权限和功能取决于设备 |
| Agent 接入 | 内置 stdio MCP 服务,返回图片和截图编号 | 可由脚本或其他 Agent 工具封装;ADB 本身不是本项目的 MCP 服务 |
| 兼容范围 | 依赖厂商接口、模拟器版本和 Windows 桌面环境 | 适用范围通常更广,但仍受 Android 设备、连接和权限条件限制 |
| 鼠标与前台 | 本项目不移动真实鼠标,不主动切换前台 | ADB 方式同样可以不移动真实鼠标,具体取决于所用方案 |

如果主要需求是让 Agent 在本机雷电或 MuMu 上看图操作,且不希望使用 ADB,本项目提供了直接的选择;如果需要管理多种 Android 设备、执行 shell 或传输文件,应考虑 ADB 或其他相应工具。本项目不替代 ADB 的全部能力,也没有速度或稳定性优于 ADB 的对比结论。

## 前提

- Windows 10/11、64 位 Python 3.11 或更新版本。
- 已安装雷电或 MuMu,保留其原生 DLL;不需要单独复制 DLL,也不会把厂商 DLL 打包进项目。
- 首次准备依赖时需要网络;环境准备完成后,本工具自身的控制流程可以离线执行。
- 调用端需要能读取 MCP 返回的图片。文本模型能调用工具,但无法仅凭文件路径理解画面。

## 启动

从 GitHub 克隆仓库:

```bat
git clone https://github.com/Kenrohoro-hub/noadb-emu-mcp.git
cd noadb-emu-mcp
```

也可以下载 ZIP 并解压,然后进入解压后的项目目录。

双击项目根目录的 `run-app.cmd`,会准备独立运行环境、显示诊断信息,并生成 `runtime/mcp-config.json`。首次失败时保留错误窗口;再次运行会检查并修复缺失的依赖。

命令行也可以从项目根执行:

```bat
run-app.cmd doctor
run-app.cmd list
run-app.cmd capture ld:0
run-app.cmd capture mumu:0
run-app.cmd state mumu:0 --state start
```

`ld:0` 表示雷电编号 0,`mumu:0` 表示 MuMu 编号 0;实际编号以 `list` 结果为准。关闭与重启分别使用 `--state stop` 和 `--state restart`,会中断该实例内正在运行的应用,不会删除实例。

管理命令会等待观察到目标运行状态。Android 刚启动时,第一张画面仍可能尚未就绪;此时重新请求截图,不要重复启动实例。

## 接入 Agent

将 `runtime/mcp-config.json` 的 `emulator-agent` 配置添加到 Agent 的 MCP 设置,然后重新加载 MCP 服务。该配置已经包含当前机器的实际项目路径和 Python 路径,不需要手工替换中文目录。

项目已更名为 NoADB Emu MCP;为保持现有接入可用,MCP 配置项、服务标识和命令行入口仍使用 `emulator-agent`,Python 模块名仍为 `emulator_agent`。本次更名不要求修改现有的客户端配置或移动项目目录。

不同 Agent 的配置文件结构可能不同;本项目生成的是常见 `mcpServers` JSON 格式。配置的实质是启动项目 `.venv` 内的 Python,执行 `main.py serve`,采用 stdio 通信,不监听网络端口。

源码安装位置改变后,重新运行 `run-app.cmd` 生成接入配置。不要将 `.venv` 复制到其他机器直接使用。

给 Agent 的操作要求可以写成:

> 使用 emulator-agent,列出模拟器,选择我指定的实例;每次先查看截图,再按返回图片的坐标操作。操作后检查新画面;遇到超时或未知结果,先重新截图,不要直接重复点击。关闭或重启实例需符合当前任务授权。

### Codex 检测注意

MCP 是工具服务,不是 Skill。先确认当前对话可调用本服务的 `list_instances` 和 `screenshot`;仅写入配置不代表旧对话已经加载。没有工具时应重新打开 Codex 后确认,不要把在受限 shell 中直接运行控制器当作 MCP 测试。

Windows 沙箱可能隔离模拟器管理程序所需的进程通信,使 MuMu 实例已有进程和窗口,却返回 Android 未启动。遇到这种矛盾,先检查调用环境;必要时申请在普通桌面会话中做只读查询和截图,不能直接认定模拟器已停止并重复启动,也不需要因此关闭沙箱或默认改为管理员运行。

实例结果的 `running` 保留厂商原始报告,判断可操作性应使用 `state`:`running` 为已提供运行标记和渲染窗口,`starting` 为窗口尚未就绪,`stopped` 为非受限查询报告停止且无进程/窗口,`unknown` 为查询受限或信息矛盾。`query_restricted` 标记当前工具是否使用 Windows 受限令牌;无法确认状态时拒绝输入和启停,不自动改用其他环境。

全量查询仍返回列表。某厂商失败时,该厂商返回 `state=query_failed`、`instance_id=null`、`running=null` 和 `error`,另一厂商的实例继续返回;失败项不能传给控制工具。查询或控制指定实例只访问对应厂商。`get_instance` 和命令行诊断中的 `tool_version` 可用来确认长驻 MCP 是否已加载新版;修改源码后需重新加载服务。

## 工具接口

| 接口 | 用途 |
| --- | --- |
| `list_instances` | 列出实例、名称、编号和运行状态 |
| `get_instance` | 查询实例、能力及管理员权限提示 |
| `set_instance_state` | 启动、关闭、重启一个指定实例 |
| `screenshot` | 返回 PNG 图片和截图编号,可裁剪、缩小 |
| `click` | 单击或双击,返回操作后画面 |
| `long_press` | 长按,最长 10 秒 |
| `swipe` | 连续滑动或拖动,最长 10 秒 |
| `press_key` | 雷电仅主页、最近任务;MuMu 另支持返回、回车和音量键 |
| `input_text` | MuMu 原生 UTF-8 文本输入;雷电明确返回不支持 |
| `cancel` | 请求停止持续操作,并取消当时已排队的动作 |

### 截图与坐标

`screenshot` 直接返回图片内容,另含 `frame_id`、返回图宽高、原始宽高、裁剪范围和时间。默认最长边不超过 1600 像素。

点击、长按和滑动必须携带同一实例的有效 `frame_id`,坐标以 Agent 实际看到的返回图片为准。裁剪或缩小后的坐标由工具换算,调用端不应再乘缩放比例。

每次输入尝试都会让之前的截图编号失效;输入成功后返回新的图片和编号。实例或工作进程重启后,旧编号也失效。截图编号不能保证页面内容一直没变,Agent 仍需在操作前判断画面是否适用。

`input_sent` 表示输入已发出,`task_verified` 始终为 false。工具无法仅凭发送成功判断游戏或应用任务已经完成。

### 多实例与取消

一个服务进程内,不同实例可以并行,同一实例操作按顺序执行。首版建议同一实例只由一个 MCP 服务会话控制,多个独立服务之间不共享队列和截图编号。

`cancel` 返回的是取消请求已发出;持续触控随后释放,排队输入和未派发的启停不再执行,以正在执行的调用最终返回为准。已发出的点击、按键、文本和管理命令不能撤销;重启在关闭阶段被取消后可能保持关闭,应重新查询。原生接口硬性卡住时会回收本工具自己创建的工作进程;结果可能未知,应重新截图确认,必要时重启该实例。

日志目录不可写或磁盘写入失败时,正常返回操作结果并附 `warnings`,不因日志失败重发输入;原操作失败时保留原错误。未裁剪、无需缩小的截图直接复用原始 PNG,裁剪与缩放仍按返回图尺寸换算坐标。

## 权限与兼容性

雷电如果以管理员运行,而 Agent 为普通权限,Windows 会拒绝后台窗口消息。诊断结果会标记 `requires_elevation`。可以通过官方管理接口先关闭、再从普通权限调用端启动雷电;如果必须保留管理员实例,则调用工具的进程也要有相应权限。工具不会自动提权、关闭安全防护或强制结束未知进程。

被其他窗口遮挡、最小化、锁屏和远程桌面断开是不同情况。首版针对遮挡场景验证;雷电最小化时主动拒绝输入。锁屏和远程桌面断开后是否可用尚未验证。

雷电首版只开放已验证的主页、最近任务键,按默认快捷键映射;用户改过快捷键时需另外适配。雷电后台返回键实测未生效,回车未验证,接口明确拒绝;可根据截图点击应用内返回等控件。`get_instance` 的 `supported_keys` 给出各后端开放的按键。

横屏、运行中旋转和 MuMu 多应用保活模式尚未完成验证,不应据竖屏测试推断支持。画面尺寸变化时工具会要求重新截图;厂商 DLL 崩溃会限制在独立工作进程内。

## 安装路径与文件

优先从 Windows 已安装程序记录识别路径,不扫描整块硬盘。没有注册信息,或同厂商安装了多个版本时,可新建项目根目录 `config.local.json`,只填需要覆盖的项:

```json
{
  "ld": "<LDPLAYER_INSTALL_ROOT>",
  "mumu": "<MUMU_INSTALL_ROOT>"
}
```

这里的 MuMu 根目录应包含 `nx_main/MuMuManager.exe`,雷电根目录应包含 `ldconsole.exe`。实际 Windows 路径中的反斜杠在 JSON 中要写成 `\\`,也可使用 `/`。

| 文件或目录 | 内容 |
| --- | --- |
| `runtime/mcp-config.json` | 当前机器的 Agent 接入配置 |
| `runtime/logs/` | 操作类型、实例、状态和耗时,不记录输入文本 |
| `runtime/*.png` | 命令行抓取的截图;MCP 默认只返回图片,不长期保存 |
| `runtime/validation/` | 本机真实验证结果与画面证据 |
| `.venv/` | 独立 Python 环境 |

运行文件和机器配置已从 Git 排除。不同机器分别准备环境,不共享活动实例、日志或 `.venv`。

## 开发验证

以下命令从项目根执行:

```bat
.venv\Scripts\python.exe -X utf8 -m unittest discover -s tests -v
.venv\Scripts\python.exe -X utf8 tests\mcp_smoke.py
```

第一条只做逻辑回归。第二条启动新 MCP 服务连接,检查版本、原图/缩小/裁剪图片与无效截图编号拒绝,不会执行有效点击;通过结果写入 `runtime/validation/mcp-smoke.json`。受限 shell 不能确认实例状态时,需要在授权的普通桌面会话运行。

`tests/live_validation.py` 是显式运行的真实设备测试,会操作两台模拟器的主页、短暂遮挡窗口、测试长按取消,并回收一个本工具工作进程。仅在允许测试当前实例时运行:

```bat
.venv\Scripts\python.exe -X utf8 -m tests.live_validation --duration 1200
```

参考接口契约:MaaXYZ/EmulatorExtras 中的 MuMu 原生头文件与雷电截图示例。接口封装按公开签名重新实现;没有复制 Alas 业务源码或包含其资源图库。

## 开源许可

本项目代码和文档采用 [MIT 许可证](LICENSE),版权声明为 `Copyright (c) 2026 Kenrohoro-hub`。第三方依赖和模拟器厂商软件分别遵循各自的许可证;本仓库不包含模拟器厂商 DLL。