内容
<div align="center">
<img src="assets/android-head_flat.svg" width="72" alt="Android 机器人标志">
# adb_mcp
**MCP 服务器，通过 `adb` 控制 Android 模拟器和设备**
[](https://github.com/iksnerd/adb_mcp/releases/latest)
[](https://github.com/iksnerd/adb_mcp/actions/workflows/ci.yml)
[](go.mod)
[](https://modelcontextprotocol.io)
</div>
---
`adb_mcp` 允许 AI 代理通过 `adb` 控制 Android 模拟器或设备 —
启动 AVD、截图、读取 UI 层次、点击/滑动/输入、设置设备锁定、
读取 `logcat`、以及管理应用生命周期。
它是 XcodeBuildMCP 的 Android 对应版本：XcodeBuildMCP 为 iOS 模拟器所做的事情，
而 `adb_mcp` 为 Android 模拟器所做。构建于官方的 Go MCP SDK 之上，
通过 stdio 进行通信。
> Android 是 Google LLC 的商标。`adb_mcp` 是一个独立的、非官方的
> Android 工具，不隶属于 Google，也不被 Google 赞助或认可。
> 上面的 Android 机器人图标是根据
> [创意共享 3.0 属性许可](https://creativecommons.org/licenses/by/3.0/) 的条款
> 修改自 Google 创建和分享的作品。
## 为什么使用 adb_mcp
手动控制 Android 设备意味着需要编写一系列原始的 `adb` 命令，
而且很容易出错（过时的点击坐标、损坏的截图、忘记 `exec-out`、
从缩略图图像中猜测坐标）。该服务器将这些知识融入其工具中，
因此代理不需要重新学习：
- 截图使用 `exec-out screencap`（无 CRLF 损坏）并且自动缩放到
图像读取器接受的尺寸。
- `describe_ui` 返回每个元素的 **真实设备像素中心** （因此点击
位于您想要的位置，而不是从图像中猜测）并且自动重试瞬时的
"无法获取空闲状态" 失败。
工作流程本身作为可读的 **资源** 提供，代理可以在任务中途调用 —
观察 → 操作循环、原生 PIN/锁定处理、崩溃排查（见下文）—
而不是在每个会话中重新学习它们。
## 快速入门
### 1. 前置条件
- 具有 `platform-tools` （`adb`）和 `emulator` 的 Android SDK。
服务器通过 `$ANDROID_HOME` / `$ANDROID_SDK_ROOT` 找到它，
否则使用平台默认值（`~/Library/Android/sdk` 在 macOS 上）。
- 至少一个 AVD（在 Android Studio 的设备管理器中创建）。
不需要 Go — 发布版本中包含预编译的二进制文件；只有在需要时才需要
[从源代码构建](#从源代码构建-需要-go-126)。
### 2. 安装
在 macOS/Linux 上：
```bash
curl -fsSL https://raw.githubusercontent.com/iksnerd/adb_mcp/main/install.sh | sh
```
脚本（[install.sh](install.sh)）为您的操作系统/架构选择正确的存档，
验证其 SHA-256 是否与发布的 `checksums.txt` 匹配，
并安装到 `~/.local/bin` （可通过 `BIN_DIR=...` 覆盖；
通过 `VERSION=v0.17.0` 固定版本）。
您是否更喜欢自己下载二进制文件？每个平台的存档 —
macOS、Linux 和 Windows，amd64 和 arm64 —
都在 [发布页面](https://github.com/iksnerd/adb_mcp/releases/latest) 上，
每个存档都有一个 `checksums.txt` 文件中的校验和。
在 Windows 上，下载 `windows_amd64` 或 `windows_arm64` zip 文件，
并将 `adb-mcp.exe` 放在您的 `PATH` 中。
安装后，通过内置的更新工具保持最新 —
它获取最新发布版本，验证其校验和，并将二进制文件替换到位：
```bash
adb-mcp update
```
下面的注册通过 `adb-mcp` 命令启动服务器，因此它必须在您的 `$PATH` 中
（`which adb-mcp` 应该解析 — 安装程序会在 `~/.local/bin` 不在 `$PATH` 中时发出警告）。
否则，请在客户端中指定二进制文件的绝对路径。
### 3. 与您的 MCP 客户端注册
**Claude 代码：**
```bash
claude mcp add adb -- adb-mcp
```
（在存储库内工作时，会自动选取 `.mcp.json` —
无需注册。）
**Cursor / VS Code** — 一键安装（假设 `adb-mcp` 已在您的 `PATH` 中
步骤 2）：
[<img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="在 Cursor 中安装" height="20">](https://cursor.com/en/install-mcp?name=adb&config=eyJjb21tYW5kIjoiYWRiLW1jcCJ9)
[<img src="https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square" alt="在 VS Code 中安装" height="20">](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522adb%2522%252C%2522command%2522%253A%2522adb-mcp%2522%257D)
**其他客户端** （Windsurf、Codex、…）：在 stdio 上运行 `adb-mcp`。
通常的配置格式：
```json
{
"mcpServers": {
"adb": { "command": "adb-mcp" }
}
}
```
要确认已连接，请让您的代理 "启动模拟器并截图"。
### 从源代码构建（需要 Go 1.26+）
```bash
make install # 构建 ./bin/adb-mcp 并复制到 ~/.local/bin
# 或：
go build -o bin/adb-mcp ./cmd/adb-mcp
# 或直接从模块（注意 /cmd/adb-mcp 后缀）：
go install github.com/iksnerd/adb_mcp/cmd/adb-mcp@latest
```
## 工具
九大类共 70 种工具。每个面向设备的工具都接受一个可选的
`serial` （adb `-s`）— 省略它时连接一个设备，或从
`list_devices` 获取一个并连接多个设备。完整参考：[docs/TOOLS.md](docs/TOOLS.md)。
- **模拟器/设备** — 启动、列出、等待启动、关闭、通过 Wi-Fi 连接、
`adb_reverse` 端口转发（Metro！）
- **观察** — `screenshot` 查看（适用于多显示屏折叠屏 —
使用 `display` 选择面板），`describe_ui` 获取真实像素中心 —
带有聚焦的 **顶部窗口** （发现阻挡应用的生物识别提示），
`filter`/`query`/`compact` 模式，以及隐藏节点计数，
以便确认其不存在
- **交互** — 点击，`tap_on_text`/`tap_element` （id 地址），滑动，
拖动，长按，输入，组合键，PIN 垫，`wait`，
`run_sequence` （批量步骤 + 保护在一个调用中 —
保持原生计时器流程不会被逐步骤往返打扰）；
可选的 `verify_change` 告诉您点击/按键是否实际更改了 UI
- **锁定 / 密钥库 / 生物识别** — 设置/清除安全锁定屏幕，
检查锁定状态，`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` 无法看到它
- **应用生命周期** — 安装/卸载，启动/停止，`app_state` （运行 pid(s) + Metro-vs-embedded 包），
`launch_dev_client` （Expo 开发版本 → Metro，跳过开发启动器），
`reload_app`/`open_dev_menu`，清除数据，权限，深层链接，
推送/拉取文件，`last_crash`
- **日志和捕获** — 一次性或流式 `logcat` （子字符串/优先级/标签过滤器，
`since` 时间窗口），`clear_logcat`，`last_crash`，屏幕录制
- **环境和诊断** — 暗黑模式，模拟位置，清理状态栏，
`stay_awake` （阻止节省电池的屏幕变黑，截图），`doctor`
- **Gradle 构建和测试** — `assembleDebug`，单元测试，仪器测试，
任务 + 变体 + 模块发现（`list_gradle_variants`/`list_gradle_projects`），
一次性 `build_and_run`
驱动程序本身作为四个 MCP **资源** （`android://guide/*`）
提供，客户端可以列出和读取 —
请参阅 [docs/TOOLS.md](docs/TOOLS.md) 获取 URI，
或直接跳转到 `android://guide/driving` 获取下面的核心循环。
## 核心循环
**观察 → 定位 → 操作 → 重新观察。**
`screenshot` 查看，`describe_ui` 获取真实像素中心，
`tap`/`tap_on_text`/`swipe`/`input_text` 操作，然后
`screenshot` 再次确认。阅读 `android://guide/driving` 获取完整循环
和可能浪费回合的陷阱。
## 开发
```bash
make check # go vet + go test （单元测试不需要模拟器）
make run # 通过 stdio 运行以进行手动 JSON-RPC 测试
```
布局：
```
cmd/adb-mcp/main.go 入口：子命令（更新/版本）或通过 stdio 提供 MCP
internal/tools/ 薄 MCP 工具绑定
internal/adb/ 设备层：adb.Client，其方法是命令
internal/gradle/ 主机端 Gradle：构建、查找 APK、解析测试报告
internal/uiauto/ 纯 uiautomator 层次结构模型 + 解析（单元测试）
internal/sdk/ 解析 Android SDK（adb/emulator 路径，PATH 环境变量）
internal/guides/ 技能指南，嵌入并作为 MCP 资源提供
internal/selfupdate/ `adb-mcp update` 版本获取/验证/交换
```
依赖关系仅指向内部（`tools → adb, gradle, uiauto → sdk`），
每个 `internal/tools/<domain>.go` 适配器 **镜像** 同名执行文件
（设备命令是 `adb.Client` 方法）。完整映射、包图和添加工具的规则：
[ARCHITECTURE.md](ARCHITECTURE.md)。
## 文档
- [docs/TOOLS.md](docs/TOOLS.md) — 完整的工具参考和指南资源
- [ARCHITECTURE.md](ARCHITECTURE.md) — 镜像约定、包布局和如何添加工具
- [docs/CHANGELOG.md](docs/CHANGELOG.md) — 已发布的作品，按最新顺序排列
- [docs/BACKLOG.md](docs/BACKLOG.md) — 开放的想法和 XcodeBuildMCP 差距
- [TODO.md](TODO.md) — 当前路线图中心
## 贡献
参见 [CONTRIBUTING.md](CONTRIBUTING.md) 获取设置和约定。
发现安全问题？参见 [SECURITY.md](SECURITY.md) 而不是公开问题。
在 [MIT](LICENSE) 下许可。
