Command Line

device-mcp-cli is Device MCP's command line. What you do in the app, or ask your AI agent to do, you can run from Terminal, a shell script, a Makefile or CI: list your devices, take screenshots, read the screen, tap and type, launch and install apps, set the location, and manage your license.

Every command can answer in JSON, so your scripts read the result with jq instead of parsing text.

1. Install#

• Homebrew: brew install --cask device-mcp puts device-mcp-cli on your PATH.
• Downloaded from the website: run this once in Terminal, to put it on your PATH:

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

The link keeps working when Device MCP updates itself. Check it with:

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

2. How it works#

• Device MCP runs your commands. Device commands go to the Device MCP app on your Mac. If it isn't running, the command asks before opening it: --launch opens it without asking (use it in scripts), --no-launch never opens it. status, mcp, tools and logs never open it.
• Which device: add --device (or -d) with a device's name or UDID. Without it, commands use the device you picked with devices select, else the one selected in Device MCP.
• JSON: add --json to any command. Errors come in JSON too.
• You stay in charge: installing and removing apps, opening links, reading or changing the clipboard and Build & Run ask you in Device MCP first, as they do for an AI agent. See Approvals. Unpairing a device and deactivating your license always ask.
• Free and Pro: every command works on Device MCP Free, except Build & Run, installing apps and the 3D view inspector, which need Device MCP Pro. Free mirrors one device at a time.

3. Commands#

<device> is a device's name or UDID. Every command takes --json; device commands take --device.

Devices#

The screen#

Touch and keys#

Apps#

Device settings#

Device MCP#

Anything else#

4. Examples#

Sign in and check the result#

A smoke test for your app, in a shell script or a CI step:

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
}

Take a screenshot of every device#

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

Tap an element on the screen#

elements lists the screen with refs. Find one with jq, then tap it:

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

Test your app in another language and place#

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

Build and run on a new simulator#

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

Record a bug#

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

Set up a Mac#

On a CI Mac or a new teammate's 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 and exit codes#

With --json, a command prints one JSON object. For example, 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"
    }
  ]
}

A device's kind is iphone, ipad, watch, android, simulator or emulator. Its state is ready, locked, blocked (with issue and fix saying why and what to do), connecting, running, shut_down, booting, shutting_down, creating or starting.

An error prints {"error": {"code": "…", "message": "…"}}:

A command that works exits with 0.

6. With your AI agent#

Your agent can use the command line too, for example to write a test script or a CI step for your app:

• "Write a script that signs in on my iPhone and fails if the home screen doesn't load."
• "Add a CI step that takes a screenshot of every screen of the onboarding."

Commands your agent runs show in the Agent tab as device-mcp-cli. See Agent Activity.