adb-mcp: Android emulator and device control over adb

---

启动 AVD、截屏、读取 UI 层级、点击／滑动／输入、设置设备锁、读取 logcat、运行 Gradle 构建和测试。可通过 stdio 从 Claude Code、Cursor、VS Code 或任何 MCP 客户端使用 80 个工具。

这是 Android 版的 XcodeBuildMCP，基于官方的 Go MCP SDK 构建。

Android 是 Google LLC 的商标。adb-mcp 是一款为 Android 构建的独立非官方 工具，与 Google 无关，也未获得 Google 赞助或认可。 上方的 Android 机器人图像复制／修改自 Google 创作并分享的作品，并依据 Creative Commons 3.0 Attribution License 中所述条款使用。

为什么使用

手动驱动 Android 意味着要执行一长串原始 adb 命令，而且很容易出错（点击坐标过期、截图被 CRLF 损坏、忘记使用 exec-out、根据缩小后的图像猜测坐标）。此服务将这些经验融入工具中，Agent 无需重新摸索：

• 截图使用 exec-out screencap（不会被 CRLF 损坏），并会自动缩小，便于图像读取器处理。
• describe_ui 会返回每个元素在设备真实像素中的中心点（这样点击就能准确落在目标位置，无需根据图像猜测），并会自动重试偶发的“无法获取空闲状态”故障。

工作流本身以易读的资源形式提供，Agent 可在任务中途随时查看（观察→操作循环、原生 PIN／锁处理、崩溃排查，见下文），无需每次会话都重新摸索。

开始使用

1. 前置条件

• 安装包含 platform-tools（adb）和 emulator 的 Android SDK。服务会通过 $ANDROID_HOME／$ANDROID_SDK_ROOT 查找 SDK，否则使用平台默认路径（macOS 上为 ~/Library/Android/sdk）。如果 MCP 客户端启动服务时未设置这些变量，请在客户端配置的 args 中传入 --sdk /path/to/sdk（服务随后会导出该变量，因此 Gradle 也能找到 SDK）。doctor 会打印解析出的路径。
• 至少有一个 AVD（在 Android Studio 的 Device Manager 中创建）。

不需要 Go：发行版已包含预构建的二进制文件，只有在从源代码构建时才需要 Go。

2. 安装

在 macOS/Linux 上：

curl -fsSL https://raw.githubusercontent.com/iksnerd/adb-mcp/main/install.sh | sh

此脚本（install.sh）会根据操作系统和架构选择合适的归档文件，将其 SHA-256 与发行版的 checksums.txt 进行校验，并安装到 ~/.local/bin（可通过 BIN_DIR=... 覆盖；通过 VERSION=v0.24.3 固定版本）。

想自行下载二进制文件？所有平台（macOS、Linux 和 Windows，amd64 和 arm64）的归档文件都在Releases 页面，每个归档都在 checksums.txt 中列有校验和。在 Windows 上，下载 windows_amd64 或 windows_arm64 zip 文件，并将 adb-mcp.exe 放到 PATH 中的某个位置。

安装后，可通过内置更新程序保持最新版本。它会获取最新发行版、校验其校验和，并就地替换二进制文件：

adb-mcp update

下面的注册配置会通过裸名称 adb-mcp 启动服务，因此它必须位于 $PATH 中（运行 which adb-mcp 应能找到它；如果 ~/.local/bin 不在其中，安装程序会发出警告）。否则，请将客户端指向二进制文件的绝对路径。

3. 注册 MCP 客户端

Claude Code：

claude mcp add adb -- adb-mcp

（在此仓库本身中工作时，会自动读取随附的 .mcp.json，无需注册。）

也可以安装为插件，它会注册服务，并为每份操作指南添加一个技能：

claude plugin marketplace add iksnerd/adb-mcp
claude plugin install adb-mcp@adb-mcp

对于 Codex，同一插件也提供 Codex 的清单格式：

codex plugin marketplace add iksnerd/adb-mcp
codex plugin add adb-mcp@adb-mcp-plugins

Claude 插件通过 node 启动服务，首次运行时会从 GitHub 发行版下载适用于你机器的构建版本，并使用固定的 SHA-256 进行校验，因此需要将 Node 放入 PATH，但无需执行第 2 步。Codex 插件仍要求 PATH 中有第 2 步安装的 adb-mcp。插件运行和发送的内容见 docs/PRIVACY.md。

Cursor / VS Code：一键安装（假设第 2 步安装的 adb-mcp 已在 PATH 中）：

任何其他客户端（Windsurf、Codex，……）：通过 stdio 运行 adb-mcp。 常见配置格式：

{
  "mcpServers": {
    "adb": { "command": "adb-mcp" }
  }
}

要确认连接正常，请让你的 Agent“启动一个模拟器并截取屏幕”。

从源代码构建（Go 1.26+）

模块固定使用 toolchain go1.26.10；首次构建时，Go 1.26 安装会自动下载该补丁版本。

make install                 # builds ./bin/adb-mcp and copies it to ~/.local/bin
# or:
go build -o bin/adb-mcp ./cmd/adb-mcp
# or straight from the module (note the /cmd/adb-mcp suffix):
go install github.com/iksnerd/adb-mcp/cmd/adb-mcp@latest

工具

80 个工具，涵盖十个领域。每个面向设备的工具都可选传入 serial（adb -s）。只连接了一台设备时可省略；连接多台设备时，从 list_devices 获取一个值传入。完整参考：docs/TOOLS.md。

• 模拟器 / 设备：启动、列出、等待启动、关机、通过 Wi-Fi 连接、adb_reverse 端口转发（Metro！）
• 观察：使用 screenshot 查看（支持多显示屏折叠设备，可通过 display 选择面板）；使用 describe_ui 获取真实像素坐标的元素中心，并显示当前聚焦的顶层窗口（可通过可选的 package 发现遮挡目标的生物识别提示，或完全错误的应用）；提供 filter/query/compact 模式，并显示隐藏节点数量，让节点确实不存在这一判断可信；render_stats 统计真实视图树和帧健康状况，而视口范围内的 describe_ui 无法做到这一点
• 交互：点按、tap_on_text/tap_element（按 ID 定位）、滑动、拖动、长按、输入、组合按键、PIN 键盘、wait、run_sequence（在一次调用中批量执行步骤和检查条件，避免逐步往返干扰使用原生计时器的流程）；选择启用 verify_change，即可获知点按/按键是否实际改变了 UI；在 tap_on_text/tap_element 上选择启用 via_accessibility（实验性），为坐标点按无法触及的原生视图分发真正的无障碍点击，参见 bridge/README.md
• 锁屏 / Keystore / 生物识别：设置/清除安全锁屏、检查锁定状态、使用 has_biometric_enrolled + fingerprint_touch/finger_remove 满足模拟器上的 BiometricPrompt 要求
• 扩展控件（模拟器）：send_sms（OTP/2FA）、phone_call、set_battery（也可通过 dumpsys 在真实设备上使用）、cellular（漫游/弱信号/限速）、set_sensor（加速度计/光线/……）、rotate_screen、avd_snapshot，用于操作 describe_ui 无法看到的模拟器纯控制台面板
• 应用生命周期：安装/卸载、启动/停止、get_app_details（已安装应用的版本和启动器 Activity，或通过 apk_path 在无设备时查询本地 APK）、app_state（运行中的 pid，以及 Metro 与嵌入式 bundle）、launch_dev_client（Expo 开发版构建 → Metro，跳过 Dev Launcher）、reload_app/open_dev_menu、清除数据、权限、深层链接、推送/拉取文件
• 日志与捕获：一次性或流式 logcat（按子字符串/优先级/标签筛选、使用 since 时间范围、选择启用 redact 在输出前遮蔽令牌/密码/API 密钥）、clear_logcat、last_crash、屏幕录制
• 环境与诊断：深色模式、模拟位置、清理状态栏、stay_awake（防止容易进入休眠状态的屏幕清空截图）、doctor
• Gradle 构建与测试：assembleDebug、单元测试、插桩测试、通过 JaCoCo 执行 JVM 单元测试覆盖率分析（get_coverage_report/get_file_coverage）、任务 + 变体 + 模块发现（list_gradle_variants/list_gradle_projects）、scaffold_android_project、一次性 build_and_run。构建会返回精简摘要（状态、错误数、首批错误、APK），完整脱敏日志则保存在磁盘上；使用 gradle_build background=true 加 build_status，可避免耗时数分钟的构建一直占用调用
• 会话默认值：通过 session_set_defaults 一次固定 project_dir/serial，这样多模块/多 flavor 项目或多设备会话就不必在每次调用时重复传入

驱动设备所需的知识本身以六个 MCP 资源（android://guide/*）的形式提供， 客户端可以列出并读取这些资源。URI 参见 docs/TOOLS.md， 也可以直接查看 android://guide/driving，了解下文的核心循环。

核心循环

观察 → 定位 → 操作 → 再次观察。 使用 screenshot 查看，使用 describe_ui 获取真实像素坐标的中心点，使用 tap/tap_on_text/swipe/input_text 执行操作，然后 再次使用 screenshot 确认。阅读 android://guide/driving，了解完整循环 以及那些会浪费操作轮次的注意事项。

开发

make check     # go vet + go test + doc-count check (unit tests need no emulator)
make run       # run over stdio for manual JSON-RPC poking

布局：

cmd/adb-mcp/main.go        entry: subcommands (update/version) or serve MCP over stdio
internal/tools/            thin MCP tool bindings
internal/adb/              the device layer: an adb.Client whose methods are the commands
internal/gradle/           host-side Gradle: builds (summary, log, background jobs), secret redaction, test and coverage reports
internal/uiauto/           pure uiautomator-hierarchy model + parsing (unit-tested)
internal/sdk/              resolves the Android SDK (adb/emulator paths, PATH env)
internal/concurrent/       RunAll/RunIndexed: fan out independent I/O calls, join, done
internal/guides/           the skill guides, embedded and served as MCP resources
internal/selfupdate/       the `adb-mcp update` release fetch/verify/swap
internal/bridgeupdate/     the `adb-mcp bridge install` release fetch/verify/install

依赖只能向内指向（tools → adb, gradle, uiauto → sdk），每个 internal/tools/<domain>.go 适配器都镜像一个同名的执行文件（设备命令是 adb.Client 方法）。完整映射、包依赖图以及添加工具的规则，请参阅：ARCHITECTURE.md。

文档

• adb-mcp.com：首页
• docs/TOOLS.md：完整的逐项工具参考和指南资源
• ARCHITECTURE.md：镜像约定、包布局以及如何添加工具
• docs/CHANGELOG.md：已发布的工作，最新内容在前
• docs/BACKLOG.md：待处理的想法和与 XcodeBuildMCP 的功能对齐差距

贡献

有关设置和约定，请参阅 CONTRIBUTING.md。发现安全问题？请参阅 SECURITY.md，不要公开提交问题。采用 MIT 许可。