Android-MCP源码架构全解析:FastMCP+uiautomator2桥接AI与安卓的底层实现
Android-MCP源码架构全解析:FastMCP+uiautomator2桥接AI与安卓的底层实现
Android-MCP 是一个用 Python 编写的轻量级 MCP Server,它通过 FastMCP 框架 + uiautomator2 库,在 AI 大模型与安卓设备之间架起一座桥梁:AI 助手不再"看图猜像素",而是直接读取界面控件树,像真人一样点击、滑动、输入文字。🤖
这个项目体量极小(核心代码不到千行),却把 MCP Server 与安卓设备通信的完整链路走通了,是非常适合入门阅读的优秀范本。本文带你逐层拆解它的底层实现。
一、项目定位:为什么需要 Android-MCP?
传统 UI 自动化(Appium、自研脚本)需要预先编写脚本或训练视觉模型,而 Android-MCP 的思路是:
- 把手机界面"翻译"成 AI 能读懂的文字:通过 ADB 抓取控件树(XML 层级),过滤出可交互元素,生成带编号的表格;
- 把 AI 的指令"翻译"成手机动作:借助 uiautomator2 将点击、滑动、输入等意图下发到设备;
- 零 CV 依赖:不需要 OCR、不需要微调视觉模型,任何 LLM/VLM 即插即用(Bring Your Own LLM)。
依赖清单见 pyproject.toml,仅 4 个核心库:fastmcp、uiautomator2、pillow、tabulate。
二、三层架构总览
整个源码位于 src/android_mcp/,清晰地分为三层:
| 层级 | 模块 | 职责 |
|---|---|---|
| ① MCP 工具层 | main.py | 创建 FastMCP 服务、注册 14 个工具、解析启动参数与设备偏好 |
| ② ADB 设备层 | mobile/ | 定位 adb 二进制、枚举/连接设备、并行抓取截图与控件树 |
| ③ UI 树解析层 | tree/ | 解析 XML 控件树、提取可交互元素、生成带标注截图 |
数据流向非常直观:
AI 客户端(Claude 等) ⇄ FastMCP 协议 ⇄ ①工具层
⇄ ②Mobile/adb 设备层
⇄ ③Tree 控件树层 → 安卓设备
三、工具层:FastMCP 如何注册一个 MCP 工具
入口文件 src/android_mcp/main.py 在模块加载时做三件事:
- 解析命令行参数(L14-L37):支持
--device、--wifi、--usb、--connection四种设备选择方式; - 创建 FastMCP 实例(L207-L208):
FastMCP(name="Android-MCP", instructions=..., lifespan=...),一段简短的 instructions 会作为"服务器说明"注入给 AI; - 用装饰器注册工具:每个 Python 函数加一行
@mcp.tool(name=..., description=..., annotations=...)就变成一个 MCP 工具,函数签名自动转为 JSON Schema 入参。
14 个工具一览
| 工具 | 作用 | 安全标注 |
|---|---|---|
ListDevices / ConnectDevice / Device |
枚举、连接、断开 ADB 设备 | readOnly / — |
Snapshot |
返回设备状态:控件表格 + 可选截图 | readOnly |
Click / LongClick |
坐标点击 / 长按 | destructive |
ClickBySelector / WaitForElement |
按 text、resourceId 等选择器操作元素 | 见 L287-L302 |
Swipe / Drag / Type / Press |
滑动、拖拽、输入文字、按系统键 | destructive |
Notification / Wait |
打开通知栏 / 固定等待 | idempotent |
ToolAnnotations 中的 readOnlyHint、destructiveHint 是 MCP 协议的安全元数据,帮助 AI 客户端区分"只读观察"与"有副作用的操作"——这个小细节是规范 MCP Server 的加分项。
惰性连接设计:服务器可以先"空转"
值得注意的设计是惰性设备连接(L185-L213):
- 服务器启动时不连接任何设备,只保存偏好(
DevicePreference); - 真正调用工具时才触发
require_device()→_connect_preferred_device(),按需解析并连接目标设备; - 偏好解析优先级:命令行参数 > 环境变量(
ANDROID_MCP_DEVICE、ANDROID_MCP_CONNECTION、ANDROID_MCP_HOST)> 自动检测; - 自动检测时优先物理设备、回退到模拟器(
emulator-前缀判定,L116-L151)。
这样即使设备还没插上,MCP 握手也不会失败——对桌面 MCP 宿主(如 Claude Desktop)极其友好。
四、设备层:adb 定位与设备连接
mobile/adb.py 解决一个不起眼但很坑的问题:MCP 宿主从 GUI 启动时,进程的 PATH 往往与终端不同,导致明明装了 Android Studio 却报 "adb not found"。
它的查找策略是三级回退(find_adb):
- 显式覆盖:
ANDROID_MCP_ADB_PATH→ADBUTILS_ADB_PATH(设了但不可执行会直接报错,而非静默回退); - 系统
PATH:shutil.which("adb"); - SDK 常见目录:
ANDROID_HOME、ANDROID_SDK_ROOT及 macOS/Linux/Windows 上 Android Studio 的默认安装路径下的platform-tools。
找到后调用 publish() 写入 ADBUTILS_ADB_PATH,确保 uiautomator2 底层的 adbutils 与自己 subprocess 用的是同一个 adb 二进制,避免版本错乱。
Mobile 类:连接与并行抓取
mobile/service.py 中的 Mobile 类是设备操作的核心:
- 设备枚举(list_devices):解析
adb devices输出;若列表为空,还会尝试通过adb mdns services发现 ADB-over-TLS 无线对端并自动连接——对无线调试场景很贴心; - 设备连接(connect):底层就是一行
u2.connect(serial),即 uiautomator2 通过 ADB 建立调试通道; - 并行抓取(capture_data):用两个线程同时拉取控件树 XML 和截图,把原本串行的 ~2 次 ADB 往返压缩为一次等待,这是"动作间隔 2-4 秒"低延迟的关键之一;
- 截图压缩(quantized_screenshot):将 PNG 量化为 256 色调色板图,配合环境变量
SCREENSHOT_QUANTIZED=true可显著降低发给 VLM 的 token 消耗。
返回的数据结构定义在 mobile/views.py:MobileState = 控件树状态 + 截图(bytes/base64/PIL Image/None)。
五、解析层:从 XML 控件树到"AI 可读"的界面
这是 Android-MCP 最有含金量的部分。安卓的 dump_hierarchy 会输出一棵包含上百个节点的 XML,直接丢给 AI 既啰嗦又没重点。tree/service.py 的 Tree 类做了三步"降噪":
1. 过滤可交互元素
is_interactive 只保留满足以下任一条件的节点:clickable、focusable、long-clickable、checkable、scrollable、password,或 class 命中白名单(如 Button、EditText、Switch,定义于 tree/config.py)。
2. 提取元素名称(含子节点兜底)
get_element_name 的取值优先级为 content-desc > text > 递归收集子节点文本——这样即使按钮本身没有 text,其内部的 TextView 文字也能被"冒泡"上来,AI 就不会看到一堆无名控件。
3. 生成编号表格 + 标注截图
- TreeState.to_string 用
tabulate输出一张Label | Name | ResourceId | Class | Coordinates纯文本表格——每个元素带编号,AI 只需说"点第 3 个"即可; - annotated_screenshot 用 PIL 在截图上为每个元素画随机颜色的编号边框,让 VLM 能同时"文字 + 视觉"双重定位;
- 坐标由 tree/utils.py 从
bounds="[x1,y1][x2,y2]"属性中解析并计算中心点。
六、完整链路:AI 是如何"点一下登录按钮"的?
把三层串起来,一次典型交互是这样流动的:
- AI 调用
Snapshot→Mobile.capture_data线程并行拉取 XML + 截图 →Tree过滤出可交互元素 → 返回表格(如3 | 登录 | btn_login | Button | (540,1200))+ 带编号边框的截图; - AI 决策:看到编号 3 是"登录"按钮,选择调用
ClickBySelector(text="登录")(或坐标点击); - 工具层下发 →
Mobile.get_device()返回 uiautomator2 的 device 对象 → 一次 ADB 指令完成点击; - AI 再次
Snapshot验证结果,形成"观察-思考-行动"闭环。
ClickBySelector 还有一个小惊喜:_resolve_resource_id 能把短 ID(btn_login)自动补全为当前前台 App 的完整 com.example:id/btn_login,降低 AI 出错概率。
七、工程化细节:一个小项目该有的样子
- manifest.json 即 Claude 扩展:manifest.json 声明了
user_config(设备序列号、连接方式、截图压缩、adb 路径四个可配置项),在 Claude Desktop 中可直接图形化配置,工具清单与__main__.py一一对应; - 测试分层:单测 tests/unit/test_tool_null_args.py 验证"所有默认 None 的参数必须接受显式 null"(防止 AI 传参踩坑);e2e_test.py 则真实启动 stdio 服务并验证"物理设备优先于模拟器"的选择逻辑;
- 贡献指南与安全说明:CONTRIBUTING.md 描述开发环境,SECURITY.md 提醒该 Server 可执行任意 UI 操作,建议在模拟器或测试机上运行不受信任的提示词。
八、快速上手:3 步跑起来
环境要求:Python 3.13 + ADB + Android 10+ 设备(README.md 有详细说明)。
第 1 步:确认设备已连接
adb devices
第 2 步:在 MCP 客户端(如 Claude Desktop)配置中以 uvx --python 3.13 android-mcp 启动,需要指定设备时追加 --device <序列号> 或 --wifi <IP>,例如:
{
"mcpServers": {
"android-mcp": {
"command": "uvx",
"args": ["--python", "3.13", "android-mcp", "--wifi", "192.168.1.3"]
}
}
}
第 3 步:重启客户端,用自然语言下达指令("打开设置,把亮度调到 50%"),即可观察 Android-MCP 如何一步步操控你的手机。
九、总结
Android-MCP 源码架构的精髓在于分工清晰、各司其职:
- FastMCP 工具层——用装饰器把函数变成 AI 可调用的工具,惰性连接保证服务器高可用;
- uiautomator2 设备层——adb 三级定位 + 线程并行抓取,把"找到设备"和"读得够快"这两件事做扎实;
- UI 树解析层——过滤、命名、编号、标注四步降噪,让 LLM 用最少 token 获得最大信息量。
如果你想给自己的 Agent 加一双"操控安卓的手",通读这份不到千行的源码,是最短路径。📱✨