android-dev-vm-mcp

在电脑上开一台开发版安卓虚拟机（headless 模拟器），通过 MCP（Model Context Protocol） 让 AI 直接调试、测试安卓应用：截屏、读 UI 树、点按输入、装包、看日志，一个工具集全包。

与现有同类项目（mobile-mcp、CursorTouch/Android-MCP 等）的差别：它们只控制"已经装好 SDK、跑着模拟器"的设备；本项目把"从零搭环境"也做进了工具链——一条命令把 Android SDK（约 2.5 GB）下载到项目文件夹内，自动建好开发用 AVD，headless 启动，全程不污染系统目录，删掉项目文件夹即完全卸载。

环境要求

• Windows 10/11（x86_64），已开启 Windows 虚拟机监控程序平台（服务 vmcompute 存在且在跑；没有就管理员终端执行 DISM /Online /Enable-Feature /All /FeatureName:HypervisorPlatform 后重启）

• Node.js ≥ 22

• Java 17+（java -version 可用即可，供 sdkmanager 使用）

Related MCP server: AndroidBuildMCP

快速开始

npm install
node cli.mjs setup      # 一次性：下载 SDK + 建 AVD（约 2.5 GB；8 路并行下载，实测系统镜像 1.5GB ≈ 2 分钟）
node cli.mjs boot       # 启动 headless 模拟器，等到 boot_completed 才返回（首次冷启动约 2 分钟）
node cli.mjs status     # 查看环境状态

把 MCP server 挂到任意 MCP 客户端（ZCode / Claude Desktop / Cursor 等），args 换成你本项目的实际路径：

{
  "mcpServers": {
    "android-dev-vm": {
      "command": "node",
      "args": ["<项目文件夹绝对路径>\\src\\server.mjs"]
    }
  }
}

之后 AI 就可以直接调用下面 25 个 android_* 工具。

工具一览（25 个）

启动后模拟器会自动关动画、屏幕常亮，保证 UI 自动化稳定。

典型 AI 工作流

android_env_status          # 确认就绪（没就绪会给出下一步）
android_emulator_boot       # 开机（幂等，已开就直接返回）
android_app_install         # 装上被测 APK（或 push + 测试）
android_logcat_clear        # 清日志
android_app_launch          # 启动应用
android_ui_dump             # 看 UI 树 → android_ui_tap 点按钮
android_screenshot          # 看实际画面
android_logcat              # 查报错

目录结构

sdk/            Android SDK（自包含，gitignore，删文件夹=卸载）
avd/            AVD 虚拟机磁盘（gitignore）
data/           运行数据：模拟器日志、pid、截屏、拉取的文件（gitignore）
src/            MCP server 与核心库（纯 ESM JS，零构建）
cli.mjs         人工入口；src/server.mjs 为 MCP stdio 入口
scripts/        selftest（协议冒烟 / 真机集成两种模式）

常见问题

• 下载慢/失败：SDK 从 dl.google.com 下载；若卡住可开加速器后再跑 node cli.mjs setup（幂等，会续上缺的组件）。

• 模拟器极慢或起不来：八成是没开 Windows 虚拟机监控程序平台，android_env_status 会提示修法。

• 端口被占：默认控制台端口 5554；被占时设环境变量 AIVM_PORT 换端口。

• 自定义镜像/机型：环境变量 AIVM_SYSTEM_IMAGE（默认 system-images;android-35;google_apis;x86_64，google_apis 可 root）、AIVM_DEVICE_PROFILE（默认 pixel_7）、AIVM_GPU（默认 swiftshader_indirect，有独显可试 host）。

许可

MIT。调研参考了 mobile-mcp、Android-MCP 等项目的工具设计思路（仅思路，未复制代码）。