Android-MCP源码架构全解析:FastMCP+uiautomator2桥接AI与安卓的底层实现

原创2026-10-23 17:09:591,848 阅读

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 在模块加载时做三件事:

  1. 解析命令行参数(L14-L37):支持 --device、--wifi、--usb、--connection 四种设备选择方式;
  2. 创建 FastMCP 实例(L207-L208):FastMCP(name="Android-MCP", instructions=..., lifespan=...),一段简短的 instructions 会作为"服务器说明"注入给 AI;
  3. 用装饰器注册工具:每个 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):

  1. 显式覆盖:ANDROID_MCP_ADB_PATH → ADBUTILS_ADB_PATH(设了但不可执行会直接报错,而非静默回退);
  2. 系统 PATH:shutil.which("adb");
  3. 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 是如何"点一下登录按钮"的?

把三层串起来,一次典型交互是这样流动的:

  1. AI 调用 Snapshot → Mobile.capture_data 线程并行拉取 XML + 截图 → Tree 过滤出可交互元素 → 返回表格(如 3 | 登录 | btn_login | Button | (540,1200))+ 带编号边框的截图;
  2. AI 决策:看到编号 3 是"登录"按钮,选择调用 ClickBySelector(text="登录")(或坐标点击);
  3. 工具层下发 → Mobile.get_device() 返回 uiautomator2 的 device 对象 → 一次 ADB 指令完成点击;
  4. 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 加一双"操控安卓的手",通读这份不到千行的源码,是最短路径。📱✨

登录后查看全文
Android-MCP