命令行

用 Device MCP 的命令行工具 device-mcp-cli，在“终端”、Shell 脚本和 CI 中操作你的 iPhone、iPad、Android 设备或模拟器。每个命令都可以用 JSON 返回结果。

device-mcp-cli 是 Device MCP 的命令行工具。你在 App 中做的事，或让 AI Agent 做的事，都可以在“终端”、Shell 脚本、Makefile 或 CI 中运行：列出设备、截图、读取屏幕、轻点和输入、启动和安装 App、设置位置，以及管理许可证。

每个命令都可以用 JSON 返回结果，因此你的脚本可以用 jq 读取结果，无需解析文本。

1. 安装

Homebrew：brew install --cask device-mcp 会把 device-mcp-cli 添加到 PATH 中。
从网站下载：在“终端”中运行一次以下命令，把它添加到 PATH 中：

sudo ln -sf "/Applications/Device MCP.app/Contents/MacOS/device-mcp-cli" /usr/local/bin/device-mcp-cli

Device MCP 自动更新后，这个链接仍然有效。用以下命令检查：

device-mcp-cli --version
device-mcp-cli --help                  # every command
device-mcp-cli help apps launch        # one command, with its options

2. 工作原理

命令由 Device MCP 执行。 设备命令会发送到 Mac 上的 Device MCP App。如果它没有运行，命令会先询问你再打开它：--launch 不询问直接打开（适合在脚本中使用），--no-launch 从不打开。status、mcp、tools 和 logs 从不打开它。
指定设备：添加 --device（或 -d），后跟设备名称或 UDID。不指定时，命令使用你用 devices select 选择的设备，否则使用 Device MCP 中选中的设备。
JSON：任何命令都可以加上 --json。错误也会以 JSON 返回。
一切由你掌控：安装和移除 App、打开链接、读取或更改剪贴板以及 Build & Run，都会先在 Device MCP 中询问你，就像 AI Agent 执行这些操作时一样。请参阅操作审批。解除设备配对和停用许可证始终会询问。
免费版与 Pro：所有命令都可在 Device MCP Free 上使用，只有 Build & Run、安装 App 和 3D 视图检查器需要 Device MCP Pro。免费版一次只能镜像一台设备。

3. 命令

<device> 是设备的名称或 UDID。每个命令都接受 --json；设备命令接受 --device。

设备

命令	作用
`devices`	列出设备：名称、类型、系统、连接方式、状态和 UDID。`--all` 还会列出所有模拟器，以及新建模拟器时可选的机型。
`devices info`	显示设备的机型、系统、屏幕尺寸、镜像状态和锁定状态。`--settings` 还会显示它的外观和辅助功能设置。
`devices select <device>`	选择后续命令使用的设备，并在 Device MCP 中显示它。
`devices start-mirroring`、`devices stop-mirroring`	开始或停止镜像设备。
`devices reconnect`	重新连接镜像画面卡住的设备。
`devices unpair <device>`	解除 iPhone 或 iPad 与 Mac 的配对。
`devices remove <device>`	将设备从 Device MCP 的列表中移除。
`simulators`	列出 iOS 和 watchOS 模拟器以及 Android 模拟器。
`simulators start <name>`	启动模拟器，并等待它运行起来。`--model "iPhone 17 Pro"` 会新建一个模拟器。
`simulators stop <name>`	关闭模拟器。

屏幕

命令	作用
`screenshot`	保存一张全分辨率截图。`-o` 指定文件（`.png` 或 `.jpg`）或文件夹；默认保存到 `~/Pictures/Device MCP`。
`record start`、`record stop`	将屏幕录制为视频，保存到 `~/Movies/Device MCP`。
`elements`	列出屏幕上的内容：每个元素的类型、标签、值、位置和尺寸，以及 ref（`e12`），供 `tap --ref` 使用。

触控和按键

命令	作用
`tap`	按文字（`--text "Sign In"`）或 ref（`--ref e12`）轻点元素，或轻点某个坐标点（`-x 120 -y 640`）。`--double` 轻点两下，`--long` 长按。
`type <text>`	在当前聚焦的输入框中输入。`--field "Email"` 填写一个输入框：轻点它、清空，然后输入。`--submit` 按下 Return 键。`-` 从管道或文件读取文本。
`scroll up\|down\|left\|right`	滚动。`--distance 300` 让内容正好移动 300 点。
`swipe --from x,y --to x,y`	从一个点滑动到另一个点。
`press <button>`	按下 `home`、`lock`、`volume_up`、`volume_down`、`mute`、`siri` 或 `back`。
`key <key>`	按下键盘按键，可配合 `--modifier command` 等修饰键。
`gesture <gesture>`	`go_home`、`app_switcher`、`control_center`、`notification_center` 或 `spotlight`。
`rotate <orientation>`	`portrait`、`landscape_left`、`landscape_right` 或 `portrait_upside_down`。
`hide-keyboard`	隐藏屏幕键盘。
`wait-for <text>`	等待文字出现在屏幕上（`--gone`：等待它消失），最多等待 `--timeout` 秒。
`alert accept\|dismiss`	回应系统弹窗，例如权限请求。`--button` 按文字轻点某个按钮。

App

命令	作用
`apps`	列出已安装的 App：名称、Bundle ID 和版本。`--user` 只列出你安装的 App。
`apps foreground`	显示前台的 App 及其 Bundle ID。
`apps launch <app>`	按 Bundle ID 或名称启动 App。测试启动时可使用 `--language`、`--locale`、`--arg` 和 `--env`。
`apps terminate <bundle-id>`	退出正在运行的 App。
`apps install <path>`	安装 `.ipa`、`.app` 或 `.apk`。需要 Device MCP Pro。
`apps uninstall <bundle-id>`	移除 App 及其数据。
`apps container <bundle-id>`	将为开发而安装的 App 的数据下载为 `.xcappdata` 包，与 Xcode 相同。
`open-url <url>`	打开网页或深层链接（`myapp://…`）。
`build-and-run <project>`	构建 Xcode 项目，然后安装并启动它。需要 Device MCP Pro。请参阅 Build & Run。
`crashes`	列出崩溃报告，最新的排在前面。`--app` 按 App 筛选。
`crashes show <path>`	显示崩溃报告：什么崩溃了、在哪里崩溃。`--app` 显示某个 App 最近一次崩溃。

设备设置

命令	作用
`location set <latitude> <longitude>`	模拟位置。`location clear` 恢复真实位置。
`appearance light\|dark`	将设备切换为浅色或深色模式。
`clipboard get`、`clipboard set <text>`	读取或替换设备剪贴板上的文本。

Device MCP

命令	作用
`status`	显示 Device MCP 是否正在运行，以及它的版本、MCP 服务器和你的许可证。
`app open`、`app quit`	在后台打开 Device MCP，或退出它。
`mcp`	显示 MCP 服务器是否已打开，以及它的地址。`mcp on` 和 `mcp off` 用于打开和关闭它。
`mcp setup claude\|codex`	将 Device MCP 添加到 Claude Code 或 Codex。`--print` 只显示命令，不执行。
`mcp config`	输出其他 MCP 客户端（例如 Cursor）使用的 JSON。
`license`	显示你的许可证：免费版，或许可证的方案、密钥、席位和涵盖的版本。
`license activate <key>`	在这台 Mac 上激活许可证密钥。
`license revoke`	在这台 Mac 上停用许可证并释放其席位。
`logs`	输出 Device MCP 的日志，用于 Bug 报告。`-f` 持续输出新的日志行。

其他

命令	作用
`call <tool> [name=value…]`	像 AI Agent 那样，运行 Device MCP 的任意 MCP 工具。
`tools`	列出这些工具及其参数。

4. 示例

为 App 做一次冒烟测试，可放在 Shell 脚本或 CI 步骤中：

set -e
device-mcp-cli apps launch com.example.myapp --launch
device-mcp-cli wait-for "Sign In"
device-mcp-cli type "[email protected]" --field "Email"
device-mcp-cli type - --field "Password" < password.txt
device-mcp-cli tap --text "Sign In"
device-mcp-cli wait-for "Welcome" --timeout 20 || {
  device-mcp-cli screenshot -o failure.png
  exit 1
}

为每台设备截图

device-mcp-cli devices --json |
  jq -r '.devices[] | select(.state == "ready" or .state == "running") | .udid' |
  while read -r udid; do device-mcp-cli screenshot --device "$udid" -o ~/Desktop/; done

轻点屏幕上的元素

elements 会列出屏幕上的元素及其 ref。用 jq 找到其中一个，然后轻点它：

REF=$(device-mcp-cli elements --json | jq -r '.elements[] | select(.label == "General") | .ref')
device-mcp-cli tap --ref "$REF"

换一种语言和地点测试 App

device-mcp-cli apps launch com.example.myapp --language fr --locale fr_FR
device-mcp-cli location set 48.8584 2.2945
device-mcp-cli open-url "myapp://map"
device-mcp-cli appearance dark

在新模拟器上构建并运行

device-mcp-cli simulators start --model "iPhone 17 Pro" --launch
device-mcp-cli build-and-run ~/Projects/MyApp/MyApp.xcodeproj --scheme MyApp
device-mcp-cli screenshot -o ~/Desktop/myapp.png

录制 Bug

device-mcp-cli record start
# reproduce the bug on the device
device-mcp-cli record stop

设置一台 Mac

在 CI 用的 Mac 或新同事的 Mac 上：

device-mcp-cli license activate --launch < license-key.txt
device-mcp-cli mcp on
device-mcp-cli mcp setup claude
device-mcp-cli status

5. JSON 与退出码

使用 --json 时，命令会输出一个 JSON 对象。例如 device-mcp-cli devices --json：

{
  "devices" : [
    {
      "connection" : "USB",
      "current" : true,
      "kind" : "iphone",
      "mirroringStopped" : false,
      "model" : "iPhone 17 Pro",
      "name" : "My iPhone",
      "osVersion" : "27.0.1",
      "platform" : "iOS",
      "state" : "ready",
      "udid" : "00008150-000A1B2C3D4E5F60"
    }
  ]
}

设备的 kind 为 iphone、ipad、watch、android、simulator 或 emulator。它的 state 为 ready、locked、blocked（附带 issue 和 fix，说明原因和解决方法）、connecting、running、shut_down、booting、shutting_down、creating 或 starting。

出错时，命令会输出 {"error": {"code": "…", "message": "…"}}：

错误代码	退出码	含义
`not_running`	69	Device MCP 没有运行且未被打开，或者在回应前退出了。
`no_answer`	69	Device MCP 正在运行但没有回应：请更新它，或退出后重新打开。
`not_installed`	69	未安装 Device MCP。
`invalid_arguments`	64	参数错误，或许可证密钥格式不正确。
`pro_required`	1	该命令需要 Device MCP Pro。
`not_approved`	1	你在 Device MCP 中拒绝了该操作，或者无人回应。
`timed_out`	1	Device MCP 未能及时完成。
`cancelled`	1	你选择了“否”。
`failed`	1	其他任何错误：消息会说明原因。

命令成功时，退出码为 0。

6. 配合 AI Agent 使用

你的 Agent 也可以使用命令行，例如为 App 编写测试脚本或 CI 步骤：

“写一个脚本，在我的 iPhone 上登录，如果首页没有加载出来就判定失败。”
“添加一个 CI 步骤，为新手引导的每个页面截图。”

Agent 运行的命令会以 device-mcp-cli 的名称显示在 Agent 标签页中。请参阅 Agent 活动。

命令行

1. 安装#

2. 工作原理#

3. 命令#

设备#

屏幕#

触控和按键#

App#

设备设置#

Device MCP#

其他#

4. 示例#

登录并检查结果#

为每台设备截图#

轻点屏幕上的元素#

换一种语言和地点测试 App#

在新模拟器上构建并运行#

录制 Bug#

设置一台 Mac#

5. JSON 与退出码#

6. 配合 AI Agent 使用#