Mobile Device Mcp

Mobile Device MCP

一个 MCP 服务，可让 AI Agent 控制 iOS 和 Android 设备（点击、滚动、输入、截图、读取 UI 树和运行代码）。可同时与多台设备配合使用。

工作原理

三层架构：

1. 设备端服务 — 在每台移动设备上运行的轻量级 HTTP 服务（Android 上为 UIAutomator，iOS 上为 XCUITest），用于公开无障碍树并接收交互命令。
2. UI 树过滤器 — 将两个平台的原始 UI 树规范化为统一的扁平元素列表。
3. MCP 服务 — 外部接口，负责设备发现、初始化、端口分配，并将请求代理到设备端服务。

首次使用时会初始化设备——服务会安装驱动应用、分配端口、启动设备端服务，并轮询直至服务正常运行。之后，所有工具调用都会通过本地主机 HTTP 代理，并使用每台设备各自的 bearer token 进行身份验证。

工具

工具	描述
list_devices	列出可用的 iOS 和 Android 设备
screenshot	截取设备屏幕（JPEG）
uitree	获取扁平列表形式的 UI 元素树，可选搜索和数量限制。默认排除屏幕外元素，除非设置 include_invisible: true
tap	点击屏幕坐标
double_tap	双击屏幕坐标
long_press	长按屏幕坐标（时长可配置）
scroll	从起始坐标滑动到结束坐标
type_text	在焦点元素中输入文本
press_button	按下硬件/导航按钮（home、back、enter、volumeUp/Down、dpadUp/Down/Left/Right/Center）
launch_app	按 bundle ID / 包名启动应用
terminate_app	强制停止应用
list_apps	列出已安装的应用
install_app	从主机本地文件安装应用（Android 使用 .apk，iOS 模拟器使用 .app，iOS 设备使用 .app/.ipa）。替换已有安装
run_code	在设备上执行沙盒化 JavaScript（见下文的 run_code）

run_code

Agent 可以传入看起来像 UIAutomator 或 XCUITest 的代码，它们底层都是 Javascript。 沙盒会限制（Android）可能有危险的 Java 操作，并且仅允许（iOS）部分类似 XCUITest 的命令

• Android： 使用 UIAutomator 绑定的 Rhino 引擎——uiDevice（点击、滑动、查找元素、按键、读取显示信息）、By（选择器）、Until（等待条件）、console.log()
• iOS： 使用 XCUITest 绑定的 JavaScriptCore——app（查询元素、点击、输入、滑动）、springboard、device、openApp(bundleId)、sleep(ms)、console.log()

两个平台都会自动终止失控脚本（无限循环），并在每次调用时创建全新沙盒。

前置条件

• Node.js 18+（通过 npx 运行）
• Android： Android SDK，且 adb 位于 PATH 中
• iOS 模拟器： Xcode，包含 xcrun、simctl
• iOS 真机： Xcode，包含 xcodebuild、devicectl 和 iproxy（来自 libimobiledevice）
• 从源代码构建： Bun 运行时、Gradle（Android）、Xcode（iOS）

安装

Claude Code

claude mcp add mobile-device-mcp -- npx -y @srmorete/mobile-device-mcp@latest

或使用自定义端口：

claude mcp add mobile-device-mcp -e MDMS_PORT_ANDROID=20000 -e MDMS_PORT_IOS=21000 -- npx -y @srmorete/mobile-device-mcp@latest

修改 .mcp.json（Cursor、Claude Desktop 等）

{
  "mcpServers": {
    "mobile-device-mcp": {
      "command": "npx",
      "args": ["-y", "@srmorete/mobile-device-mcp@latest"],
      "env": {
        "MDMS_PORT_ANDROID": "18000",           # optional
        "MDMS_PORT_IOS": "19000"                # optional
      }
    }
  }
}

从源代码构建

git clone <repo-url>
cd mobile-device-mcp
bun install

# Build drivers for both platforms and pack tarball
./scripts/build.sh

构建脚本会编译设备端驱动（通过 Gradle 构建 Android APK，通过 xcodebuild 构建 iOS 测试包），将它们复制到 drivers/，并创建 npm 压缩包。

开发期间可在本地运行：

bun run start           # Start the MCP server
bun test                # Run the test suite

配置

环境变量	默认值	描述
MDMS_PORT_ANDROID	18000	Android 设备端服务的基础端口
MDMS_PORT_IOS	19000	iOS 设备端服务的基础端口

端口按顺序分配——第一台 Android 设备使用 18000，第二台使用 18001，依此类推。iOS 设备也采用相同方式，从 19000 开始。

致谢

Mobile Device MCP server 的开发借鉴了 mobile-mcp 和 Maestro 等项目的成果。 这些项目为我们提供了灵感，我们据此重新设计了当前方案，使其支持多设备，并能无缝支持原生界面/WebView（尤其是在 Android 上）。

许可证

MIT