内容
# uiautomator2-mcp
Android 设备自动化 MCP（模型上下文协议）服务器，通过 [uiautomator2](https://github.com/openatx/uiautomator2) 实现。
使 AI 代理（如 Claude）能够控制 Android 设备 - 点击、滑动、输入文本、截取屏幕、管理应用程序等。
## 前提条件
- Python 3.10+
- [uv](https://docs.astral.sh/uv/getting-started/installation/)（推荐）或 pip
- 已启用 USB 调试的 Android 设备（或模拟器）
- 已安装 ADB 且设备可通过 `adb devices` 显示
## 快速入门
### Claude 代码 - 一条命令即可添加并自动运行：
```bash
claude mcp add uiautomator2 -- uvx uiautomator2-mcp
```
就这样。Claude 将在需要时自动启动服务器。
### Claude 桌面版
在 `claude_desktop_config.json` 中添加：
```json
{
"mcpServers": {
"uiautomator2": {
"command": "uvx",
"args": ["uiautomator2-mcp"]
}
}
}
```
### Codex CLI
选项 1 - 通过 CLI 添加：
```bash
codex mcp add uiautomator2 -- uvx uiautomator2-mcp
```
选项 2 - 添加到 `~/.codex/config.toml`（或项目 `.codex/config.toml`）：
```toml
[mcp_servers.uiautomator2]
command = "uvx"
args = ["uiautomator2-mcp"]
```
### opencode
在您的 opencode 配置（`opencode.json` 或 `opencode.jsonc`）中添加 `uiautomator2-mcp` 作为本地 MCP 服务器：
```jsonc
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"uiautomator2": {
"type": "local",
"command": ["uvx", "uiautomator2-mcp"],
"enabled": true
}
}
}
```
保存配置后，启动 opencode 并要求它使用 `uiautomator2` MCP 工具。有关更多详细信息，请参阅 [opencode MCP 服务器文档](https://opencode.ai/docs/ru/mcp-servers)。
### 替代方法
```bash
# 使用 pipx
pipx run uiautomator2-mcp
# 使用 pip（全局安装）
pip install uiautomator2-mcp
uiautomator2-mcp
# 使用 python -m
pip install uiautomator2-mcp
python -m uiautomator2_mcp
# 从源码
git clone https://github.com/stayer147/uiautomator2mcp.git
cd uiautomator2mcp
pip install -e .
uiautomator2-mcp
```
## 可用工具（45）
### 连接
| 工具 | 描述 |
|------|-------------|
| `list_devices` | 列出 ADB 可见的设备及其是否在 MCP 会话中连接 |
| `list_avds` | 列出已配置的 Android 虚拟设备 |
| `start_emulator` | 在后台启动 Android 模拟器 |
| `connect` | 通过序列号/IP 或自动检测连接设备 |
| `disconnect` | 从 MCP 会话中断开已连接的设备 |
| `device_info` | 获取设备型号、屏幕尺寸、Android 版本 |
### UI 交互
| 工具 | 描述 |
|------|-------------|
| `tap` | 点击屏幕坐标 |
| `multi_tap` | 多次点击相同坐标 |
| `double_tap` | 在坐标处双击 |
| `long_tap` | 在坐标处长按 |
| `swipe` | 在两点之间滑动 |
| `drag` | 在两点之间拖动 |
| `input_text` | 在聚焦的字段中输入文本 |
| `press_key` | 按下设备按键（主页、返回、输入等） |
### 复合动作
| 工具 | 描述 |
|------|-------------|
| `tap_and_wait` | 点击元素，等待下一个 UI 状态，并返回新的层次结构快照 |
| `tap_sequence` | 执行验证的点击、等待、输入、按键和滑动序列 |
### 元素操作
| 工具 | 描述 |
|------|-------------|
| `find_element` | 通过文本、资源 ID、类、描述或 XPath 查找元素 |
| `tap_element` | 查找并点击元素 |
| `double_tap_element` | 通过选择器或 XPath 查找并双击元素 |
| `set_element_text` | 在输入字段中设置文本 |
| `element_exists` | 检查元素是否存在 |
| `wait_element` | 等待元素出现 |
### 截图和 UI 层次结构
| 工具 | 描述 |
|------|-------------|
| `screenshot` | 截取截图作为保存的文件或内联 JSON/base64 图像有效载荷 |
| `dump_hierarchy` | 获取 XML UI 层次结构或紧凑的文本摘要 |
| `get_ui_tree` | 获取具有元素状态的更丰富的 JSON UI 树，供代理分析 |
#### 代理友好分析输出
- `screenshot(inline=True)` 返回一个 JSON 对象，其中包含 base64 编码的图像数据、MIME 类型、尺寸和字节大小，以便 MCP 客户端无需打开文件系统路径即可渲染图像。
- `screenshot(save_path="/tmp/screen.jpg", quality=70, max_width=1280)` 保留原始的磁盘保存工作流程，同时允许控制调整大小/压缩。
- `get_ui_tree()` 返回一个结构化的 JSON 数组，其中包含 `text`、`resource_id`、`class_name`、`content_desc`、`bounds`、`clickable`、`enabled`、`focused`、`selected`、`checked`、`scrollable` 和 `index`。
- `dump_hierarchy(compact=True)` 作为每行一个元素的轻量级快照仍然可用，而 `dump_hierarchy(compact=False)` 仍然返回原始 XML。
### 应用管理
| 工具 | 描述 |
|------|-------------|
| `app_start` | 启动应用 |
| `app_stop` | 强制停止应用 |
| `app_install` | 安装 APK |
| `app_uninstall` | 卸载应用 |
| `app_clear` | 清除应用数据 |
| `app_info` | 获取应用信息 |
| `app_list_running` | 列出正在运行的应用 |
| `current_app` | 获取当前前台应用 |
### 设备控制
| 工具 | 描述 |
|------|-------------|
| `screen_on` | 唤醒设备 |
| `screen_off` | 关闭屏幕 |
| `unlock` | 解锁设备 |
| `open_notification` | 打开通知面板 |
| `open_quick_settings` | 打开快速设置 |
| `get_clipboard` | 获取剪贴板内容 |
| `set_clipboard` | 设置剪贴板内容 |
### 诊断
| 工具 | 描述 |
|------|-------------|
| `clear_logs` | 清除设备上的 logcat 缓冲区 |
| `get_logs` | 按包、级别、时间戳和行数读取过滤的 logcat 输出 |
### Shell 和文件
| 工具 | 描述 |
|------|-------------|
| `shell` | 在设备上运行 shell 命令 |
| `push_file` | 将文件推送到设备 |
| `pull_file` | 从设备拉取文件 |
## 示例工作流程
当 MCP 会话中只连接一个设备时，工具可以省略 `device_id`。如果连接多个设备，请显式传递 `device_id`。现在，多设备定位在交互式 UI、应用程序管理、设备控制、监视器、剪贴板和文件传输工具以及诊断工具（如 `clear_logs` 和 `get_logs`）中得到一致支持。
1. **列出可用设备**：`list_devices()`
2. **连接**到一个设备：`connect("emulator-5554")`
3. **可选地连接第二个设备**：`connect("emulator-5556")`
4. **检查特定设备**：`device_info(device_id="emulator-5554")`
5. **截取屏幕截图**以查看当前屏幕：`screenshot(device_id="emulator-5554")` 或请求内联 JSON/base64 输出，最大宽度为 1080：`screenshot(inline=True, max_width=1080, device_id="emulator-5554")`
6. **转储层次结构**以了解轻量级 UI 结构：`dump_hierarchy(device_id="emulator-5554")`
7. **获取更丰富的 UI 树**当状态很重要时：`get_ui_tree(device_id="emulator-5554")`
8. **点击元素**按文本或资源 ID
9. **直接通过 XPath 双击**在需要时，例如 `double_tap_element(xpath="//android.widget.TextView[@text='Gallery']")`
10. **在输入字段中输入文本**
11. **截取另一个屏幕截图**以验证结果
## 示例错误报告工作流程
1. **清除旧日志**：`clear_logs()`
2. **使用 UI 交互工具重现错误**
3. **捕获错误日志**：`get_logs(level="E", package="com.example.app")`
4. **截取失败状态的屏幕截图**，可选内联用于视觉分析
5. **转储层次结构**用于轻量级快照或 `get_ui_tree()` 用于更丰富的元素状态
## 示例登录在一个工具调用中
```python
tap_sequence(
steps=[
{"action": "tap_element", "resource_id": "com.example:id/email"},
{"action": "input_text", "text": "user@example.com"},
{"action": "tap_element", "resource_id": "com.example:id/password"},
{"action": "input_text", "text": "correct horse battery staple"},
{"action": "tap_element", "resource_id": "com.example:id/sign_in"},
{"action": "wait", "resource_id": "com.example:id/home_feed", "timeout": 15}
]
)
```
## 发布到 PyPI
```bash
uv build
uv publish
```
发布后，`uvx uiautomator2-mcp` 将开箱即用。
## 许可证
MIT
