# 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](https://mobilenext.ai/docs/docs/mobilecli/overview.md) 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[​](#prerequisites "Direct link to Prerequisites")

* macOS with Xcode command-line tools installed (`xcode-select --install`)
* [MobileCLI](https://mobilenext.ai/docs/docs/mobilecli/installation.md) 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[​](#find-your-device "Direct link to 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[​](#real-device-with-a-wildcard-certificate "Direct link to 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[​](#real-device-without-a-wildcard-certificate "Direct link to 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](https://developer.apple.com/account/resources), 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[​](#ios-simulator "Direct link to 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[​](#next-steps "Direct link to Next steps")

With the agent installed, follow the [installation guide](https://mobilenext.ai/docs/docs/mobile-mcp/quick-start.md#supported-agents) for your agent to connect Mobile MCP, then explore the [Tools Reference](https://mobilenext.ai/docs/docs/mobile-mcp/tools-reference.md) to see everything the agent can do on a device.