开源雷达 2026-10-11

来源:github · 原文链接:https://github.com/mobile-next/mobile-mcp · 整理:github_bot · 发布时间:2026-10-11


一、项目概览

mobile-next/mobile-mcp 是一个面向移动开发与自动化的轻量级 MCP 服务器。它把 iOS 与 Android 上的设备操作抽象成一套平台无关的接口,让智能体和 LLM 能够在模拟器、仿真器和真机上执行点击、输入、滑动、应用管理与信息提取,而使用者无需掌握 XCUITest、Espresso 或任一平台的专门知识。

项目用 TypeScript 实现,以 Apache-2.0 协议开源,npm 包名为 @mobilenext/mobile-mcp。仓库目前约 8.9k star、800 fork,属于 MCP 生态中少见的「硬件侧」项目——大多数 MCP 服务器在跟文件和 API 打交道,而它直接操控一台正在运行的真实设备。

它同时支持本地与云端两种执行路径:本地依赖 adb 与 xcrun simctl,云端则通过 Mobile Next Cloud 预约真机,工具集完全一致。对已经习惯在终端里跑 Claude Code 或 Codex 的开发者来说,这意味着移动端自动化第一次有了和 Web 端 Playwright 等价的入口,尽管成熟度还处在追赶阶段。

二、核心特性速览

特性具体表现工程价值
无障碍优先基于原生 accessibility 树驱动应用,不调用视觉模型不消耗图像 token,单步成本显著低于纯截图方案
截图回退仅在无障碍树无法覆盖时回退到截图 + 坐标点击兼顾 Canvas、游戏等非标准 UI 的可操作性
一套 API 横跨双端同一组工具覆盖 iOS/Android、模拟器/仿真器/真机智能体的提示词与工具调用逻辑无需按平台分叉
结构化输出读取真实 UI 元素并提取结构化数据结果确定、可断言,比「看图猜位置」更利于多步推理
无需平台专业知识不需要写 XCUITest/Espresso,也不需要平台胶水代码把移动自动化的门槛从「移动工程师」降到「会写提示词」
终端内镜像Claude Code 插件提供 /mobile-mirror,在侧栏实时查看并操作设备调试闭环留在终端,不必在模拟器与编辑器之间来回切换

这里的核心取舍值得点明:无障碍树优先是整个项目的成本模型基石。视觉方案每一步都要把整屏截图塞进上下文,长流程下 token 消耗呈线性甚至超线性增长;而无障碍快照只返回元素文本、类型、坐标和可交互状态,既便宜又便于模型做精确引用。

三、系统架构设计

Mobile MCP 系统架构

整个系统可以按三层来理解:交互接入层、核心编排层、设备能力层。

交互接入层由智能体客户端(MCP Client)与 MCP 服务器(MCP Server)构成。客户端可以是 Claude Code、Codex、Gemini、GitHub Copilot、Antigravity 或任何兼容 MCP 的宿主,它通过「调用工具」把自然语言意图转成对具体工具的请求;服务器本身支持 stdio 与 Streamable HTTP 两种传输,前者适合本地 IDE 插件式集成,后者适合托管与水平扩展场景。

核心编排层是项目真正的主体。工具调度核心(server.ts)承担「注册分发」职责:它把设备管理、应用管理、屏幕交互、输入导航、日志崩溃等数十个工具注册进 MCP 协议层,并把每次调用路由到对应的实现。与之并列的还有两个横向模块——技能插件(plugin/ 与 skills/)在工作流层提供「加载技能」的扩展点;安全校验(MOBILEMCP_AUTH)则在请求进入工具前完成「鉴权校验」,校验通过后才「放行调用」。这两条支线说明项目已经不满足于做一个玩具式 demo,而是按可运维服务的标准在设计。

设备能力层由 MCP 工具集、无障碍快照与设备执行层共同组成。工具集向下有两条主要通路:一条「读取 UI 树」,从设备的无障碍服务拉取元素快照,经 format-elements.ts 与 coordinate-mapping.ts 归一化后返回给模型;另一条「下发指令」,通过 adb、xcrun simctl 或 mobilecli 把点击、输入、按键等动作真正打到设备上。此外还有一条旁路通往云设备池(Cloud Devices),由核心层发起「预约云机」,把本地无设备的情况交给远程真机池兜底。

值得称道的是分层边界:robot.ts 与 mobile-device.ts 定义的抽象让平台差异被压缩在 android.ts、ios.ts、iphone-simulator.ts 这几个文件里,上层工具完全不必知道自己是面对一台 Pixel 还是一台 iPhone 模拟器。这种「薄适配层 + 厚编排层」的结构,是它能用一套 API 覆盖四种目标类型的关键。

四、核心流程或主循环

移动自动化主循环

移动自动化的主循环本质上是一个「感知—决策—执行—校验」的闭环,Mobile MCP 把它拆成六个站点,由 MCP 会话上下文(Session State)作为中枢串联。

第一步,列出设备。 智能体调用 mobile_list_available_devices,拿到当前可用的模拟器、仿真器与已连接真机。这一步同时起到健康检查的作用:如果列表为空,说明平台工具链或设备授权有问题,后续所有操作都无意义。

第二步,启动应用。 通过 mobile_launch_app 以包名或 bundle ID 拉起目标应用,必要时先 mobile_install_app 安装 APK/IPA。到这里为止都是确定性的准备工作,不涉及模型推理。

第三步,获取快照。 这是整个循环的信息入口。mobile_list_elements_on_screen 返回带坐标和属性的元素列表,mobile_take_screenshot 在无障碍树信息不足时补位。快照质量直接决定后续决策质量——元素文本缺失或层级混乱时,模型很容易点错位置。

第四步,规划动作。 LLM 基于当前快照与任务目标决定下一步做什么。这是循环中唯一真正依赖模型能力的环节,也是最昂贵的一环。快照越结构化、噪声越少,这一步的推理越短、越稳定。也正因如此,mobile_batch_commands 这类工具才有价值:把「点击→输入→点击」这类确定性序列合并成一次调用,省掉中间轮的推理开销。

第五步,执行交互。 通过 mobile_click_on_screen_at_coordinates、mobile_type_keys、mobile_swipe_on_screen、mobile_press_button 等把决策落地。执行层屏蔽平台差异,Android 走 adb 系指令,iOS 走 mobilecli 或 WebDriver 路径。

第六步,校验结果。 再次读取屏幕元素或截图,确认动作是否生效。校验结果通过「结果回传」写回会话上下文,同时更新状态——包括当前前台应用、屏幕方向、剪贴板等。然后回到第三步,进入下一轮。

这个循环的关键在于每轮都重新读屏。与「一次性生成完整脚本再执行」的批处理模式相比,逐步闭环对界面变化的容忍度高得多,代价是往返次数多、延迟叠加。对探索式任务和长尾 App 流程,这是正确的取舍;对需要高频重复的回归测试,则应该转向 mobilewright 这类确定性方案。

五、核心模块解析

模块职责
src/server.tsMCP 服务器主体,负责工具注册、请求分发与传输层对接(stdio / Streamable HTTP)
src/index.ts程序入口,解析 --listen 等命令行参数并启动服务
src/android.tsAndroid 平台机器人实现,基于 adb 完成设备控制、应用管理与 UI 读取
src/ios.tsiOS 真机机器人实现,处理设备配对、应用安装与交互指令
src/iphone-simulator.tsiOS 模拟器实现,走 xcrun simctl 路径,是 macOS 上最常用的目标后端
src/mobile-device.ts设备抽象层,定义跨平台设备应具备的统一能力契约
src/robot.ts机器人基类与公共逻辑,屏蔽上层对具体平台的感知
src/mobilecli.ts与 mobilecli 二进制的桥接,作为新版默认执行引擎
src/format-elements.ts把原始无障碍节点格式化成模型友好的元素列表
src/coordinate-mapping.ts坐标空间换算(设备像素 ↔ 逻辑坐标 ↔ 截图坐标)
src/webdriver-agent.tsWebDriver 协议代理,用于需要该路径的场景
src/jpeg.ts / src/png.ts图像编解码,服务于截图与录屏功能
src/logger.ts / src/utils.ts日志与通用工具函数

从模块划分能看出一个清晰的意图:平台差异被刻意收窄。真正跟 Android 或 iOS 强绑定的代码集中在三个平台文件里,其余都是与平台无关的编排、格式化和工具函数。coordinate-mapping.ts 单独成文件尤其说明问题——不同设备的缩放、密度与截图分辨率不一致是移动自动化最常见的踩坑点,把它提炼为独立模块,比散落在各处做换算要可靠得多。

六、特色能力

手势层面,项目提供了完整的触控原语:单击、双击、长按、四方向滑动,并且都可以指定精确坐标,必要时还能设置滑动时长以模拟不同力度的拖拽。

设备层面,能力覆盖得相当完整:应用安装(支持 .apk、.ipa、.app、.zip)、启动、终止、卸载;屏幕录制开始与停止;硬件按键(HOME、BACK、VOLUME_UP/DOWN、ENTER 等);通过 mobile_open_url 打开深度链接;屏幕方向读取与切换;GPS 位置覆盖;剪贴板读写。这些能力单独看都不稀奇,但被统一进同一套 MCP 工具命名规范里,对智能体而言就是「一次学习、处处可用」。

诊断能力是另一个加分项。mobile_get_device_logs 可以采集 Android logcat 或 iOS unified log,mobile_list_crashes 与 mobile_get_crash 能列出并读取完整崩溃报告。这意味着智能体不仅能操作界面,还能在流程失败时自己去看日志定位原因——这是从「自动化脚本」迈向「自主调试」的必要一步。

还有一个颇具巧思的功能:Claude Code 插件提供的 /mobile-mirror。它适用于在 Ghostty 或 kitty 中运行的 Claude Code,安装插件后在侧边窗格显示设备实时画面,并允许直接点按、输入文字、触发 Home/Back。这等于把设备调试面板塞进了终端,对习惯终端工作流的开发者是很实在的体验改进。

七、工具链或生态

Mobile MCP 不是一个孤立项目,它是 Mobile Next 工具集的一环,三个组件形成明确的层次:

  • mobilecli —— 底层通用设备 CLI,通过命令行或 JSON-RPC 控制设备、模拟器与仿真器。Mobile MCP 的执行能力大量构建于其上(src/mobilecli.ts 就是那座桥)。
  • mobilewright —— 定位为「移动端的 Playwright」。当智能体驱动的探索式操作需要固化成可重复、确定性的测试时,就该迁移到这一层。
  • Mobile Next Cloud —— 同一套技术栈的按需租用版本,随时可用的真实 iOS 与 Android 设备。 生态集成方面,仓库提供了 plugin/(含 hooks 与类型定义)、skills/mobile-automation/、Dockerfile、smithery.yaml、mcp.json、server.json、glama.json、manifest.json 等资产,基本把主流 MCP 分发渠道都覆盖了。传输层支持 stdio 与 Streamable HTTP,后者明确标注为无状态(无需会话亲和性),直指 Smithery 这类水平扩展托管平台的部署需求。客户端侧则明确列出 Claude Code、Codex、Gemini、GitHub Copilot、Antigravity 的兼容性。

八、部署与安全

上手成本极低,一段配置即可接入:

{
  "mcpServers": {
    "mobile-mcp": {
      "command": "npx",
      "args": ["-y", "@mobilenext/mobile-mcp@latest"],
      "env": {
        "MOBILEMCP_DISABLE_TELEMETRY": "1"
      }
    }
  }
}

前置条件只有三项:Xcode 命令行工具、Android Platform Tools、node.js v20 及以上。本地开发用 stdio 即可;需要给团队或 CI 共享时,改用 HTTP 模式:

MOBILEMCP_AUTH=my-secret-token npx @mobilenext/mobile-mcp@latest --listen 0.0.0.0:3000

此时所有请求必须携带 Authorization: Bearer my-secret-token,未设置时会接受未认证连接并输出警告——这个默认行为需要注意,服务化部署时务必显式配置 token。绑定到 localhost 时会自动启用基于 Host 头的 DNS 重绑定防护,这是一个细节到位的安全设计。

其余环境变量各司其职:MOBILEMCP_ALLOW_UNSAFE_URLS 默认阻止非标准 URL scheme,避免智能体被诱导执行 tel:、file: 之类的高风险跳转;MOBILEMCP_DISABLE_TELEMETRY 关闭 PostHog 与 Scarf 的匿名遥测;MOBILEMCP_LEGACY_ROBOT 可回退到旧版平台专用 robot(Android 与 iOS 真机生效,iOS 模拟器仍走 mobilecli)。隐私上,项目声明本地运行、仅与所连接设备通信。

九、适用场景

原生应用的自动化测试与数据录入是最直接的用法:让智能体走完注册、下单、填表等流程,并读取界面结果做校验。相比传统 UI 自动化框架,省去了定位器维护的负担,代价是稳定性略逊。

LLM 驱动的多步骤用户旅程是它的主场。README 给出的示例很能说明定位——搜视频、点赞、评论、分享到 WhatsApp;下载计步应用、注册、设番茄钟、回应用商店打五星;在 Substack 搜索文章、高亮段落、加入阅读列表。这类任务步骤长、界面陌生、无预置脚本,正是逐步读屏 + 动态规划的优势区间。

免手动的设备脚本化流程适用于任何「需要在手机上点很多下」的场合:装包、跑冒烟用例、批量配置设备、跨应用数据搬运。

智能体框架的通用移动交互能力则是更基础的用法:作为 Agent 工具箱里的一块拼图,为上层提供移动端感知与操作的原语。

需要提醒的是,支付、转账、账号安全设置这类高风险流程不建议交给它自主执行,目前缺少足够细粒度的操作确认与回滚机制。

十、总结评价

Mobile MCP 的真正价值不在于「让 AI 会点手机」,而在于它选对了抽象层次。无障碍树优先这个决定,同时解决了三个问题:成本(不烧图像 token)、确定性(结构化元素可断言)、以及跨平台一致性(iOS 与 Android 的无障碍语义虽有差异,但经过 format-elements.ts 归一化后对模型呈现为同一套形状)。在这个基础之上,「一套 API 覆盖模拟器、仿真器与真机」才不是一句口号,而是分层设计的自然结果。

适用人群很清晰:一是想在移动端复刻 Web 端 AI 自动化体验的前端/全栈开发者,二是需要快速验证 App 流程的产品与测试人员,三是把移动操作当作能力模块接入自有 Agent 框架的工程师。对已经有一套稳定 Appium/Espresso 体系的大型测试团队,它的吸引力相对有限——探索式自动化的不确定性,反而可能成为流水线里的噪声源。清晰度也要打折:项目 API 面已经很宽,但版本号仍停留在 0.0.1,接口存在变动风险。

局限性同样要讲清楚。第一,执行速度受限于逐步闭环,每轮都要读屏 + 推理,长流程耗时远高于脚本化方案;第二,无障碍树覆盖不全的场景会退化,游戏、Flutter/Metal 自绘界面、WebView 内部元素的质量参差不齐,回退到坐标点击后稳定性明显下降;第三,依赖本地工具链,Windows 上无法跑 iOS 模拟器,CI 环境中的设备管理依然麻烦——这也正是 Mobile Next Cloud 存在的理由;第四,默认无鉴权的 HTTP 模式需要部署者自己留心。

把它放在 Mobile Next 的工具矩阵里看,定位就更清楚了:mobilecli 是设备抽象层,Mobile MCP 是探索层,mobilewright 是固化层。三者构成一条从「能用 AI 跑通」到「能进 CI 稳定跑」的演进路径。这条路是否走得通,取决于探索式自动化在真实项目里的稳定性天花板有多高——而 8.9k star 至少说明,愿意尝试的人已经不少了。

参考链接:项目仓库 · 官网与云设备 · Wiki 文档