Skip to main content
View as Markdown

Getting Started: iOS

To control an iOS device, Mobile MCP relies on an on-device agent for touch input (taps, swipes, button presses), screen capture streaming, and UI tree inspection — capabilities that aren't available through standard iOS tooling. MobileCLI installs and manages this agent for you.

On a simulator the agent installs with no code signing. On a real device the agent must be re-signed for your device with an Apple provisioning profile, so the steps differ depending on whether you have a wildcard certificate.

Prerequisites​

  • macOS with Xcode command-line tools installed (xcode-select --install)
  • MobileCLI installed (npm install -g mobilecli)
  • Node.js v22 or later
  • For a real device: an Apple Developer account and a device connected over USB with trust established

Find your device​

List the connected simulators and devices to get the device ID you'll pass to later commands:

mobilecli devices

You can check whether the agent is already installed on a device at any time:

mobilecli agent status --device <device-id>

Real device with a wildcard certificate​

A wildcard provisioning profile (App ID *) can sign the agent regardless of its bundle identifier, so this is the simplest path. Point agent install at your .mobileprovision file:

mobilecli agent install --device <device-id> --provisioning-profile ~/Downloads/Wildcard_Dev.mobileprovision

If only one device is connected, you can omit --device. MobileCLI re-signs the agent with your profile and installs it. On success you'll see a JSON result like this:

{
  "status": "ok",
  "data": {
    "message": "Agent installed successfully",
    "agent": {
      "version": "0.0.18",
      "bundleId": "com.mobilenext.devicekit-iosUITests.xctrunner"
    }
  }
}

Use --force to reinstall over an existing agent.

Real device without a wildcard certificate​

If you don't have a wildcard profile (for example, on a free personal Apple ID or under an organization that only issues explicit profiles), you need a provisioning profile whose App ID explicitly matches the agent's bundle identifier, com.mobilenext.devicekit-iosUITests.xctrunner.

  1. In the Apple Developer portal, register an explicit App ID for com.mobilenext.devicekit-iosUITests.xctrunner.

  2. Register your device's UDID under Devices (find it with mobilecli devices).

  3. Create a Development provisioning profile that ties that App ID, your signing certificate, and your device together, then download the .mobileprovision file.

  4. Install the agent with that profile:

    mobilecli agent install --device <device-id> --provisioning-profile /path/to/profile.mobileprovision
note

Free personal Apple IDs can't create wildcard App IDs, and their provisioning profiles expire after 7 days — you'll need to reinstall the agent when the profile lapses. A paid Apple Developer account with a wildcard profile avoids this.

iOS Simulator​

Simulators don't require code signing, so no provisioning profile is needed. Installing the agent manually is optional — Mobile MCP automatically installs it on a simulator whenever it's needed.

If you'd like to install it ahead of time, boot a simulator and run agent install with no provisioning profile:

# Boot a simulator (or start it from Xcode)
mobilecli device boot --device <simulator-id>

# Install the agent — no provisioning profile required
mobilecli agent install --device <simulator-id>

Next steps​

With the agent installed, follow the installation guide for your agent to connect Mobile MCP, then explore the Tools Reference to see everything the agent can do on a device.

Last updated on