androidbuild-mcp

AndroidBuildMCP

让你的 AI Agent 亲自操作 Android。AndroidBuildMCP 是一款 MCP 服务，可让任何 MCP 客户端（Claude Code、Cursor 等）构建、部署、操作和调试真实的 Android 应用：提供易读错误信息的 Gradle 构建、模拟器管理、adb 部署、logcat 捕获和完整的 UI 自动化。

快速开始

要求：Node 18+、Android SDK（通过 ANDROID_HOME 指定或使用默认安装路径），以及用于 Gradle 构建的 JDK 17+。

无需安装步骤——首次运行时，npx 会获取该服务。

Claude Code

claude mcp add androidbuild -- npx -y @asjackson/androidbuild-mcp

其他 MCP 客户端

{
  "mcpServers": {
    "androidbuild": {
      "command": "npx",
      "args": ["-y", "@asjackson/androidbuild-mcp"]
    }
  }
}

git clone https://github.com/dev-jackson/androidbuild-mcp.git
cd androidbuild-mcp
npm install && npm run build
claude mcp add androidbuild -- node /absolute/path/to/androidbuild-mcp/dist/index.js

然后让你的 Agent 运行 doctor——它会检查 SDK、adb、模拟器、Java 和已连接设备，并准确告知缺少什么。

你的 Agent 可以做什么

• 构建和测试 — build_app 会编译项目，并返回精简的 file:line 编译错误，而不是上千行 Gradle 输出。test_app / test_instrumented 会返回解析后的通过/失败摘要。还包括 Lint、清理和覆盖率（Kover/Jacoco）。
• 管理模拟器 — 列出、创建、启动（等待完全启动并返回序列号）、清除和关闭 AVD。设置 GPS 位置、深色模式，以及用于截图的干净演示状态栏。
• 部署 — build_run 一次调用即可完成编译、安装和启动。通过 adb 安装、卸载、清除数据、查看应用信息；仅连接一台设备时会自动选择该设备。
• 查看屏幕 — snapshot_ui 会将 UI 作为紧凑的命名元素列表返回，并附带点击坐标（合并 Compose 语义并过滤噪声）。screenshot 会返回图像；设置 annotate: true 后，会使用视觉功能绘制带编号的框，识别图像和 WebView 中的文本。
• 操作屏幕 — 点击、滚动、滑动、拖动、长按、输入文字（支持键盘，并可清除/提交）、使用硬件按键，以及通过 wait_for_ui 轮询直到指定元素出现。
• 读取日志 — 在后台捕获经过应用过滤的 logcat、一次性转储日志，以及获取包含堆栈跟踪的崩溃缓冲区。
• 启动新应用 — scaffold_android_project 会生成一个开箱即用、可直接构建的最小 Compose 项目。

会话默认设置（session_set_defaults）让你只需配置一次项目、模块、变体和设备——之后的所有调用都无需传入参数。

工具参考

共 53 个工具，通过 stdio 使用。每个工具都接收普通参数并返回文本（screenshot 除外，它会返回图像）。

环境和项目

会话默认值

构建、测试和质量

设备和模拟器

应用生命周期

UI 自动化

日志和录制

脚手架

精准点击

所有 adb 端操作共用一个坐标空间（设备像素），但 MCP 客户端通常会对屏幕截图进行缩放——凭肉眼估算图像中的像素位置，会导致点击落在错误位置。以下三种方式都能安全地命中目标：

1. snapshot_ui — 返回每个命名元素的精确设备像素中心坐标。首选。
2. screenshot { annotate: true } + tap_element { element: N } — 按图像上标出的编号点击；映射是在原始 PNG 上解析的，因此客户端缩放不会造成偏差。
3. tap { xPct, yPct } — 使用屏幕百分比（0-1），long_press/swipe/drag 也支持此方式。与分辨率无关。

如果你掌握真实的像素坐标，仍可使用原始的 tap { x, y }。

可靠性

发布前，每种工具都在真实模拟器和真实项目中进行了测试，涵盖常规流程和边界情况；逐个场景的证据见 qa-results.md。以下细节有助于避免 Agent 工作流出错：

• type_text 会等待软键盘出现后再输入（否则，聚焦字段后立即输入会悄悄丢掉开头的几个字符）。
• scroll 会根据屏幕尺寸计算长而慢的滑动——短而快的滑动会被某些列表忽略。long_press 会按住 1000 ms，这是启动器所要求的。
• 点击屏幕外的位置时，会返回实际屏幕尺寸，而不是悄无声息地无操作。
• 文本密集型屏幕（电子书 WebView 等）会限制内容量，并可通过 snapshot_ui { filter } 搜索，避免上下文被大量内容占满。
• 构建/测试/设备故障会返回简短且可执行的消息，并指出下一步要调用的工具。

可选附加项

• Google 的 Android CLI 支持 screenshot { annotate: true }。doctor 会输出适用于你操作系统的一行安装命令。
• ADBKeyboard IME 支持输入非 ASCII 字符的 type_text（adb 本身只支持 ASCII）。安装一次其 APK 即可；服务会自动使用它。

开发

npm install
npm test            # unit tests (no real processes spawned)
npm run dev         # run the server from source
npm run build       # compile to dist/

许可证

MIT — 详见 LICENSE。

概念上受 XcodeBuildMCP 启发；这是围绕 Android 工具链构建的独立实现。