Agent-Android

简体中文 | English

Agent-Android 是一个通过原生 ADB 控制 Android 设备的本地 MCP Server，同时提供可选的 Web 控制台。AI Agent 与浏览器用户复用同一套控制层，可管理 USB、无线 ADB 和多台设备。

适合 Android 自动化测试、重复操作、Agent 实验、真机任务编排和人工协同控制。当前版本：0.3.2。

[!WARNING] 本项目能够点击屏幕、启动应用、输入文字和触发真实外部操作。只在你拥有或获准控制的设备上运行，并在发送消息、付款、删除数据等操作前保留人工确认。

主要能力

• 27 个 MCP 工具：设备发现、截图、点击、滑动、按键、文字输入、应用管理、UI 树、OCR、等待条件和无线配对。
• Agent-first UI 操作：screen_summary、find_element、wait_for_element、tap_element。
• Unicode 输入：通过用户自行提供并核验的 ADBKeyBoard 输入中文和 Emoji，并恢复原输入法。
• Web 控制台：实时画面、点击/拖动、应用列表、UI/OCR 标注和活动日志。
• 多进程安全：MCP 与 Web 通过设备文件锁串行化命令；Web 截图流会为 Agent 操作让路。
• 本地持久化：SQLite/WAL 保存设备和最近 500 条操作，敏感文字和配对码自动脱敏。
• 远程访问边界：Web 默认仅监听 127.0.0.1，支持 API Token 与 Tailscale Serve。

Windows EXE

从 Releases 下载 Agent-Android.exe 或便携 ZIP，直接双击 EXE：

1. 自动检查电脑上是否已有 adb；
2. 如果没有，显示 Google 官方 Android SDK License 和 Platform Tools 发布页；
3. 用户阅读后输入 ACCEPT，程序从 dl.google.com 直接下载 stable Windows Platform Tools， 并校验 Google 仓库元数据公布的文件大小和 SHA-1；
4. 启动只监听 127.0.0.1:8765 的内置 Web 控制台并打开默认浏览器；
5. 关闭控制台窗口或按 Ctrl+C 即停止服务。

EXE 已包含 Agent-Android、Python 运行时以及 OCR/scrcpy 的 Python 侧依赖，不需要另装 Python 或 Git。由于 Android SDK License 的再分发边界， Release 不捆绑 adb.exe；只有用户明确同意许可后，程序才会从 Google 官方仓库下载到 %LOCALAPPDATA%\Agent-Android\platform-tools。ADBKeyBoard APK、scrcpy-server 和手机厂商 USB 驱动也不会捆绑。

因此在有网络的新 Windows 电脑上，下载一个 EXE 即可完成软件侧环境；手机仍需开启开发者选项和 USB/无线调试，部分品牌的 USB 连接还需要厂商驱动。

命令行模式：

.\Agent-Android.exe                 # 启动 Web 控制台并打开浏览器
.\Agent-Android.exe web             # 启动 Web 控制台，不自动打开浏览器
.\Agent-Android.exe web --open-browser
.\Agent-Android.exe setup           # 交互式安装 Google Platform Tools
.\Agent-Android.exe setup --accept-android-sdk-license
.\Agent-Android.exe mcp             # 启动 stdio MCP Server
.\Agent-Android.exe --version

首次注册 MCP 前，先在普通控制台完成 ADB 设置，避免许可提示进入 MCP stdio：

.\Agent-Android.exe setup
codex mcp add agent-android -- "C:\path\to\Agent-Android.exe" mcp

一键部署 MCP

前置条件

• Windows 10/11
• Git for Windows
• Python 3.11
• Android SDK Platform Tools（adb）
• 手机已开启开发者选项和 USB/无线调试

安装器不会下载 ADBKeyBoard APK 或 scrcpy-server，也不会绕过 Android 的设备授权。

Codex

在 PowerShell 中运行：

$p = "$env:TEMP\install-agent-android.ps1"; Invoke-WebRequest https://raw.githubusercontent.com/xiaoran7/Agent-Android/main/scripts/install.ps1 -OutFile $p; powershell -ExecutionPolicy Bypass -File $p

脚本会：

1. 克隆或更新仓库到 %LOCALAPPDATA%\Agent-Android；
2. 创建隔离的 Python 3.11 虚拟环境并安装 MCP 包；
3. 自动发现 adb；
4. 注册名为 agent-android 的 Codex stdio MCP Server；
5. 输出当前可见设备。

重新打开 Codex 任务后即可使用。

Claude Desktop

$p = "$env:TEMP\install-agent-android.ps1"; Invoke-WebRequest https://raw.githubusercontent.com/xiaoran7/Agent-Android/main/scripts/install.ps1 -OutFile $p; powershell -ExecutionPolicy Bypass -File $p -Client claude

安装完成后重启 Claude Desktop。

只安装，不修改客户端配置

.\scripts\install.ps1 -Client none

可选依赖：

.\scripts\install.ps1 -WithOcr
.\scripts\install.ps1 -WithScrcpy
.\scripts\install.ps1 -WithOcr -WithScrcpy

建议先查看 scripts/install.ps1 再执行远程安装命令。

手动安装

git clone https://github.com/xiaoran7/Agent-Android.git
cd Agent-Android
.\scripts\setup_venv.ps1
.\scripts\check_adb.ps1

启动 MCP：

.\.venv\Scripts\agent-android.exe mcp

也可以使用模块入口：

.\.venv\Scripts\python.exe -m agent_android.cli mcp

Codex 手动注册示例：

codex mcp add agent-android --env "ADB_PATH=C:\Android\platform-tools\adb.exe" -- "C:\path\to\Agent-Android\.venv\Scripts\python.exe" -m agent_android.cli mcp

其他支持 stdio MCP 的客户端可参考 .mcp.json.example。

快速验证

连接设备后，让 Agent 执行：

列出已连接的 Android 设备，读取当前屏幕摘要，然后告诉我当前前台应用。

建议的安全操作顺序：

1. list_devices
2. screen_summary
3. find_element / wait_for_element
4. 在必要时执行 tap_element、input_text 等动作
5. 再次读取 UI 或前台应用，验证真实结果

动作调用返回成功不等于目标应用一定完成了业务操作。对消息发送、表单提交等外部副作用，应读取操作后的 UI 进行确认。

MCP 会一直运行吗？

不会因为安装而成为 Windows 常驻服务。Agent-Android 使用 stdio MCP：

• Codex 或 Claude 启动 MCP 进程，并在同一客户端会话内复用它；
• 客户端断开或退出后，MCP 进程通常随之结束；
• 每次工具调用不会额外启动一个新进程；
• 双击 EXE 启动的是持续运行的 Web 控制台，不是 MCP；关闭窗口或按 Ctrl+C 即结束；
• Android 的 adb server 是独立的后台进程，可能在 MCP 退出后继续存在，可用 adb kill-server 停止。

Agent-Android 自身不会在 Android 手机上安装常驻控制服务；ADBKeyBoard 和可选的 scrcpy-server 由用户独立提供，并遵循各自的生命周期。

Unicode 文字输入

原生 adb shell input text 可能被中文拼音输入法截获。可靠的中文和 Emoji 输入需要 ADBKeyBoard：

.\scripts\install_adb_keyboard.ps1 -DeviceId "<device-id>" -ApkPath "C:\path\to\ADBKeyboard.apk"

项目不会自动下载或信任第三方 APK。请自行核验来源和哈希后提供文件。

input_text(method="auto") 仅在 ADBKeyBoard 可用时工作；否则明确失败，不会悄悄降级到可能误报成功的原生输入。

部分 vivo OriginOS 版本会通过私有 fast_freezer 机制冻结或杀死 ADBKeyBoard。当前代码会等待 IME 切换并处理常见冻结唤醒，但长期无人值守任务仍应读取目标输入框确认文字确实落地。详见 gotchas。

Web 控制台

本机启动：

.\.venv\Scripts\agent-android.exe web

打开 http://127.0.0.1:8765。

带随机 Token 启动：

.\scripts\start_secure_web.ps1

不要把无 Token 的服务绑定到 0.0.0.0。异地访问优先使用 Tailscale Serve。

低延迟 scrcpy 预览是可选功能，需要自行核验并提供 scrcpy-server：

.\scripts\install_scrcpy_server.ps1 -JarPath "C:\path\to\scrcpy-server-v4.1" -Version "4.1"
$env:AGENT_ANDROID_STREAM_BACKEND = "scrcpy"
.\.venv\Scripts\agent-android.exe web

配置

常用环境变量：

变量	用途
ADB_PATH	adb 可执行文件路径
AGENT_ANDROID_DATA_DIR	SQLite、锁和可选二进制的数据目录
AGENT_ANDROID_WEB_HOST	Web 监听地址，默认 127.0.0.1
AGENT_ANDROID_WEB_PORT	Web 端口，默认 8765
AGENT_ANDROID_API_TOKEN	非回环 Web 访问所需 Token
AGENT_ANDROID_STREAM_BACKEND	screenshot 或 scrcpy

一键安装时默认数据目录为 %LOCALAPPDATA%\Agent-Android。源码 editable 安装默认使用仓库内的 data/。

开发与验证

.\scripts\setup_venv.ps1
.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\python.exe -m ruff check .
.\.venv\Scripts\python.exe -m ruff format --check .
.\.venv\Scripts\python.exe -m bandit -q -r src
.\.venv\Scripts\python.exe -m build
.\scripts\build_exe.ps1

当前基线：104 项自动化测试，Ruff 与 Bandit 通过；主要能力已在 Android 模拟器和两台 vivo 真机上验证。

构建产物位于 dist/：

python -m pip install .\dist\agent_android-0.3.2-py3-none-any.whl
agent-android mcp

已知边界

• 当前定位是个人或可信小团队使用，不是公网多租户平台。
• Session Cookie 仍与原始 API Token 同值，不能单独吊销单个会话。
• scrcpy 子进程生命周期主要依赖真机验证，自动化覆盖仍有限。
• Android OEM 的输入法、后台冻结和无线调试行为可能不同。
• Tailscale Serve 只保护 Web 控制台，不会隧道化 Wireless ADB。

完整记录见 开发踩坑与遗留项。

文档

• Agent 使用指南
• 系统架构
• 设备与无线调试
• Tailscale 安全部署
• 开发踩坑记录
• 变更记录
• 贡献指南
• 安全策略

许可证

本项目采用 MIT License。