用 mobile-mcp 让编码 Agent 直接操作手机：无障碍树驱动的真机与模拟器自动化实操

浏览器自动化已经卷成了红海——browser-use、Operator、Computer Use 各家都在做「会操作网页的 Agent」。但每天真正占据人类注意力的屏幕是手机，而手机的自动化长期以来只有两条难路：视觉模型截图点击（贵、慢、不稳定），或者厂商封闭的私有协议。mobile-next 开源的 mobile-mcp（Apache-2.0）走了第三条路：把一套 MCP 工具直接铺到 iOS/Android 的模拟器与真机上，Agent 读的是原生无障碍树——不需要视觉模型、不烧图像 token、输出结构化且确定，需要时才回退到截图加坐标。一套工具覆盖 Android 模拟器、iOS 模拟器、USB 真机与云端真机，接进任何支持 MCP 的客户端（Claude Code、Claude Desktop、Cursor、Codex CLI 等），你的编码 Agent 就顺手把手机也管了。

🎯 适合人群：想给自己的 Agent 加手机操作能力的开发者、需要真机回归与自动化验证的移动端团队。前置：Node.js 20+；Android 路线装 Android Platform Tools，iOS 路线需要 macOS 加 Xcode 命令行工具。

先理解：无障碍树优先，截图只是备胎

mobile-mcp 的架构关键词是 accessibility-first：它驱动应用时读取的是操作系统维护的原生无障碍树，把屏幕内容整理成结构化的元素清单（类型、文本、坐标、属性）交给模型，模型基于这份「文本地图」决策点什么、填什么。对照截图方案的优势很直接——不消耗图像 token、不依赖多模态模型、元素定位是确定性的而不是视觉猜测。只有当无障碍树拿不到足够信息时（自绘控件、游戏画面），它才回退到 mobile_take_screenshot 加坐标点击。这个设计也划定了能力边界：你的应用无障碍做得越好，Agent 干活越准——反过来说，重度自绘 UI 的应用要降低预期。

与纯视觉方案（如教程 182 的 Open-AutoGLM）路线不同，选型别混。mobile-mcp 是「给现有 MCP 客户端加手机工具」，轻、省、确定性强，但依赖应用的无障碍语义；视觉方案不挑 UI 但成本高。选择取决于你的目标应用 UI 是否规范，而不是哪个更「先进」。

Step 1：环境准备，把模拟器跑起来

1 Android 用 adb 验证，iOS 用 simctl 启动

# 通用前提：Node.js 20+
node -v

# Android 路线：安装 Android Platform Tools 后验证
adb devices
# List of devices attached
# emulator-5554   device

# iOS 路线（仅 macOS）：列出并启动一个模拟器
xcrun simctl list
xcrun simctl boot "iPhone 16"

Android 侧两条路：用 Android Studio 建一个 AVD 模拟器（开发测试最方便），或直接连真机——真机要在开发者选项里打开 USB 调试，插上电脑后手机弹出授权对话框点允许，adb devices 里出现 device 状态才算就绪。iOS 侧模拟器仅限 macOS（xcrun simctl boot 启动），真机连接需要设备信任这台电脑。验证标准很简单：设备列表里能看到目标设备，后面的所有工具才有用武之地。

真机授权等于把设备的完全控制权交给这台电脑。公共电脑、他人电脑上不要点「允许 USB 调试授权」；测试用机与个人主用机分开，是移动自动化团队的基本纪律。

Step 2：接入 MCP 客户端，一条命令或一段 JSON

2 Claude Code 用 CLI，桌面端用配置文件

// Claude Desktop 及多数 MCP 客户端的 JSON 配置
{
  "mcpServers": {
    "mobile-mcp": {
      "command": "npx",
      "args": ["-y", "@mobilenext/mobile-mcp@latest"]
    }
  }
}

# Claude Code 一条命令接入
claude mcp add mobile-mcp -- npx -y @mobilenext/mobile-mcp@latest

# Codex CLI / Gemini CLI 同理
codex mcp add mobile-mcp npx "@mobilenext/mobile-mcp@latest"
gemini mcp add mobile-mcp npx -y @mobilenext/mobile-mcp@latest

mobile-mcp 走标准 stdio 传输，npx -y 免安装直接拉起，所以接入成本几乎为零。配置完成后验证方式很直接：对 Agent 说 list available devices，它能列出你正在运行的模拟器或真机，就说明整条链路（客户端 → MCP server → 平台工具 → 设备）全通。Cursor 用户走设置界面手动添加（Settings → MCP → Add，类型选 command，命令填上面那串 npx）；各客户端的详细配置 JSON 官方 README 都给了现成的，复制即可。

💡 npx 拉包慢或环境受限的团队，先 npm install -g @mobilenext/mobile-mcp 再把 command 换成本地 bin 路径，离线环境也能用。

Step 3：认识工具面，掌握「列元素 → 操作 → 验证」循环

3 三组工具构成一个完整的操作闭环

# 设备与应用管理
mobile_list_available_devices     # 列出模拟器/真机
mobile_list_apps                  # 已装应用
mobile_launch_app / mobile_terminate_app
mobile_install_app                # 支持 apk / ipa / app / zip

# 屏幕交互（无障碍树优先）
mobile_list_elements_on_screen    # 结构化元素清单 + 坐标属性
mobile_click_on_screen_at_coordinates
mobile_type_keys / mobile_press_button   # HOME / BACK / ENTER 等
mobile_take_screenshot            # 必要时的兜底

# 观测与批量
mobile_get_device_logs            # Android logcat / iOS unified log
mobile_batch_commands             # 一次调用顺序执行多个工具

日常操作就是三步循环：mobile_list_elements_on_screen 拿到当前屏幕的结构化清单 → 模型决策要点的元素与要填的内容 → 执行点击或输入 → 再列一次元素验证操作生效。这个循环和浏览器自动化里「快照 → 操作 → 快照」的心智完全一致，做过网页 Agent 的团队可以无缝迁移。效率细节：mobile_batch_commands 能把多个工具调用合并成一次往返，对「打开应用 → 等待 → 点击 → 输入」这类固定序列特别合适，省掉多轮模型往返的延迟。

💡 给 Agent 的指令里多说「预期看到什么」——比如「点击后应该出现设置页的列表」，模型会主动用元素清单去核对，操作失败时也能自己发现并重试。

Step 4：实战两个真活儿，装包验证与设置修改

4 一句话指令，让 Claude Code 全程自动完成

# 场景一：装包验证（移动端发版前的例行检查）
"把 build/outputs/apk/debug/app-debug.apk 装进模拟器，
启动它，等首页出现后截图给我确认"

# 场景二：设置修改（系统级操作）
"在模拟器上打开设置，把深色模式打开，
回到主屏幕后截图确认"

预期效果：Agent 会自动列设备、调 mobile_install_app 装包、mobile_launch_app 启动、读无障碍树确认首页元素出现（比如断言某个标题文本存在），用截图收尾。你会发现「断言类任务」是这套工具的甜区——「确认某文本出现了吗」这类问题，结构化元素清单直接回答，不需要 OCR 也不需要猜。团队可以把这类验证写进发版流程：打包脚本跑完，把 apk 路径交给 Agent 做冒烟验证，人只看最终截图与结论。

💡 任务失败时让它 mobile_get_device_logs 拉一段 logcat，崩溃栈就在里面——Agent 自己就能把「装了起不来」的原因找出来，这是把日志工具也给它的价值。

Step 5：进阶观测，崩溃、录屏与 GPS 覆写

5 测试工程的常用武器都在工具面里

# 崩溃排查：列崩溃再取详情
mobile_list_crashes
mobile_get_crash

# 录屏（自动化过程的留档与复现）
mobile_start_screen_recording
mobile_stop_screen_recording

# GPS 覆写：测试 LBS 类功能的虚拟定位
mobile_set_location

# 其他：剪贴板 mobile_clipboard、横竖屏 mobile_set_orientation

这几组工具把 mobile-mcp 从「演示玩具」拉到了「测试工程工具」的位置：崩溃列表加崩溃详情，让 Agent 能自动复现问题并附上崩溃栈；录屏把自动化过程留档，回归测试的证据链有了；mobile_set_location 覆写 GPS 后可以验证外卖、打车、天气这类位置相关功能的边界城市行为。组合用法举例：「把定位设到乌鲁木齐，打开天气应用，确认温度单位与城市名正确，录屏留档」——一句话就是一个过去要人肉跑到测试机前操作的用例。

「伪造环境」类工具只用于测试。GPS 覆写、虚拟定位用于功能测试天经地义，但拿它绕过服务的风控、伪造签到打卡属于违规使用，账号风险自担；团队内部也要有工具使用范围的书面约定。

Step 6：服务化与安全边界，远程模式的三道闸

6 --listen 起 HTTP 服务，鉴权与遥测用环境变量管

# HTTP 模式（默认是 stdio）：Streamable HTTP
npx @mobilenext/mobile-mcp@latest --listen 3000

# 对外暴露必须加鉴权
MOBILEMCP_AUTH=your-strong-token npx @mobilenext/mobile-mcp@latest --listen 3000

# 关闭匿名遥测
MOBILEMCP_DISABLE_TELEMETRY=1

stdio 模式够用在本机个人场景；当你想把手机工具挂给团队共用（比如一台测试机机器上起服务，多个开发者的 Agent 远程调用），就用 --listen 起 Streamable HTTP 服务——注意旧版 HTTP+SSE 传输已被移除，客户端要用 Streamable HTTP 方式连接，远程模式是无状态的、不需要会话亲和。安全上三道闸缺一不可：鉴权（设 MOBILEMCP_AUTH 后强制 Bearer token，不设时服务会接受未认证连接并打警告——别忽略这个警告）、网络边界（防火墙只放行可信网段）、遥测开关（合规敏感环境用 MOBILEMCP_DISABLE_TELEMETRY=1 关掉匿名遥测）。

另外两个默认值要知道：mobile_open_url 默认封锁非标准 URL scheme（防止 Agent 被诱导拉起任意应用），确有需要才设 MOBILEMCP_ALLOW_UNSAFE_URLS=1 放开；--listen 0.0.0.0 等于把手机控制权暴露到网络，只在内网加鉴权时使用。

常见问题速查

你遇到的现象	大概率原因和解决
list devices 返回空	Android：adb 未授权或模拟器没起（先跑 adb devices 核对）；iOS：模拟器未 boot 或 Xcode 工具链未装
真机连上但操作失败	USB 调试未授权（重插手机看弹窗）；iOS 真机未信任电脑。授权后重试
自定义控件点不中	自绘控件无障碍语义缺失。先 list elements 看能不能列到该元素，列不到就回退坐标点击，长期靠补 accessibility 标注
HTTP 客户端连不上	旧客户端还在用 HTTP+SSE 传输。升级客户端走 Streamable HTTP（POST /mcp）
远程服务被异常调用	没设 MOBILEMCP_AUTH。立即加鉴权并换端口，检查设备上有没有异常操作痕迹
担心使用数据外传	默认匿名遥测走 PostHog 与 Scarf，设 MOBILEMCP_DISABLE_TELEMETRY=1 关闭

← 返回教程中心