Control a real iPhone from a Mac
An agent drives a USB iPhone through WebDriverAgent, a test app that runs on
the phone and answers HTTP on port 8100. It taps, types, swipes, launches apps
and returns the screen's element tree. go-ios opens the tunnel that iOS 17
and later need. mobile-mcp exposes the same actions as MCP tools.
Stop point: the agent never unlocks the phone and never types a passcode.
The owner unlocks it. Ask before any tap that changes a setting, sends a
message, buys, or deletes.
Decide the route
| Route |
What you get |
Cost |
| WebDriverAgent + go-ios |
Taps, typing, element tree, app launch |
Xcode build, developer signing |
| + mobile-mcp |
The same, as MCP tools in the agent |
One mcp add |
xcrun devicectl device capture screenshot alone |
Screenshots, no input |
Developer Mode on |
| iPhone Mirroring + Mac input injection |
Taps through a Mac window |
Same Apple ID on both, phone locked |
WebDriverAgent cannot read another app's private files. It sees only what is
on the screen.
Requirements
- Xcode signed in to a developer account: Xcode > Settings > Accounts. A
free account signs for 7 days, so rebuild weekly. A paid account signs for a
year. Check:
security find-identity -v -p codesigning.
- The team ID is the
OU of the Apple Development certificate:
security find-certificate -c "Apple Development" -p | openssl x509 -noout -subject.
- Developer Mode on the phone, the phone on USB, and "Trust This Computer"
accepted.
npm install -g go-ios (provides ios), brew install libimobiledevice.
Set up
The iphone-wda script in
itsryanarmani/scripts does every step:
IPHONE_WDA_TEAM=<team id> iphone-wda up # build, install, tunnel, forward, wait
iphone-wda open com.apple.Preferences
iphone-wda tree # type | label | value per element
iphone-wda find General # drag until visible, then tap
iphone-wda shot screen.png
By hand, the same steps are:
- Clone
appium/WebDriverAgent into its own directory.
xcodebuild build-for-testing -scheme WebDriverAgentRunner -destination id=<udid> -allowProvisioningUpdates DEVELOPMENT_TEAM=<team> PRODUCT_BUNDLE_IDENTIFIER=com.<you>.WebDriverAgentRunner.
The stock bundle ID belongs to another team and fails signing.
ios tunnel start --userspace in the background. No sudo needed.
xcodebuild test-without-building -xctestrun <file> -destination id=<udid> in
the background. The log prints ServerURLHere->http://<ip>:8100.
ios forward 8100 8100, then curl localhost:8100/status.
Add mobile-mcp, pinned:
CLAUDE_CONFIG_DIR=<config dir> command claude mcp add mobile-mcp -s user -- npx -y @mobilenext/mobile-mcp@<version>
mobile-mcp finds real devices through go-ios and expects WebDriverAgent on port
8100. Its tools load only in a new agent session.
Traps
Each of these cost a cycle on a real iPhone running iOS 27.
| Symptom |
Cause |
Fix |
Unable to log in with account ... login details were rejected |
Xcode's saved account session expired |
The owner signs in again in Xcode > Settings > Accounts |
Unlock <name> to Continue in the test log |
The phone is locked |
The owner unlocks it; the run continues by itself |
/wda/locked is false but app launch fails with could not be unlocked |
/wda/locked reports the screen is on, not that the passcode was entered |
Test unlock by launching an app, as iphone-wda wait does |
| A Settings row is missing from the tree |
Settings builds rows lazily, and /wda/swipe did not scroll it |
Drag by coordinates (/wda/dragfromtoforduration) until the row appears |
An alert covers the screen but /alert/dismiss says no alert is open |
A system alert, such as an account password prompt, is outside the app's tree |
Screenshot, then tap the button by point. Points are pixels divided by the screen scale |
App-prefs: URL opens Settings > Apps |
iOS 27 no longer routes those paths |
Navigate by taps |
| Settings search finds no result for a page |
Search does not index every page |
Navigate by taps |
| A tap by label opened the wrong page |
A label match hit a row in another list |
Use exact labels, and check the navigation bar after each tap |
claude mcp add wrote to another account's config |
A claude shell function picked a different CLAUDE_CONFIG_DIR |
Run command claude with CLAUDE_CONFIG_DIR set |
idevicescreenshot fails with Invalid service |
It needs a developer disk image it cannot mount |
Use xcrun devicectl device capture screenshot |
Verify
curl -s localhost:8100/status shows "ready" : true.
iphone-wda open com.apple.Preferences then iphone-wda tree prints the
Settings rows.
- A screenshot shows the screen you expect.
Related skills
1---2name: ios-device-control3description: "Use when an agent must operate a real iPhone from a Mac: open apps, read the screen, tap, type, scroll and take screenshots, for example to read Settings or check an app. Sets up WebDriverAgent with go-ios and mobile-mcp over USB, and lists the traps that each cost a real cycle on iOS 27. Never unlocks the phone and never enters a passcode. Triggers: 'give the agent access to my iPhone', 'control my phone from the Mac', 'tap through Settings on my iPhone', 'mobile-mcp real device'."4metadata:5 source: https://skillmd.com/skills/pooriaarab/ios-device-control6---78# Control a real iPhone from a Mac910An agent drives a USB iPhone through **WebDriverAgent**, a test app that runs on11the phone and answers HTTP on port 8100. It taps, types, swipes, launches apps12and returns the screen's element tree. **go-ios** opens the tunnel that iOS 1713and later need. **mobile-mcp** exposes the same actions as MCP tools.1415**Stop point:** the agent never unlocks the phone and never types a passcode.16The owner unlocks it. Ask before any tap that changes a setting, sends a17message, buys, or deletes.1819## Decide the route2021| Route | What you get | Cost |22|---|---|---|23| WebDriverAgent + go-ios | Taps, typing, element tree, app launch | Xcode build, developer signing |24| + mobile-mcp | The same, as MCP tools in the agent | One `mcp add` |25| `xcrun devicectl device capture screenshot` alone | Screenshots, no input | Developer Mode on |26| iPhone Mirroring + Mac input injection | Taps through a Mac window | Same Apple ID on both, phone locked |2728WebDriverAgent cannot read another app's private files. It sees only what is29on the screen.3031## Requirements3233- Xcode signed in to a developer account: **Xcode > Settings > Accounts**. A34 free account signs for 7 days, so rebuild weekly. A paid account signs for a35 year. Check: `security find-identity -v -p codesigning`.36- The team ID is the `OU` of the Apple Development certificate:37 `security find-certificate -c "Apple Development" -p | openssl x509 -noout -subject`.38- Developer Mode on the phone, the phone on USB, and "Trust This Computer"39 accepted.40- `npm install -g go-ios` (provides `ios`), `brew install libimobiledevice`.4142## Set up4344The `iphone-wda` script in45[itsryanarmani/scripts](https://github.com/itsryanarmani/scripts) does every step:4647```sh48IPHONE_WDA_TEAM=<team id> iphone-wda up # build, install, tunnel, forward, wait49iphone-wda open com.apple.Preferences50iphone-wda tree # type | label | value per element51iphone-wda find General # drag until visible, then tap52iphone-wda shot screen.png53```5455By hand, the same steps are:56571. Clone `appium/WebDriverAgent` into its own directory.582. `xcodebuild build-for-testing -scheme WebDriverAgentRunner -destination id=<udid>59 -allowProvisioningUpdates DEVELOPMENT_TEAM=<team> PRODUCT_BUNDLE_IDENTIFIER=com.<you>.WebDriverAgentRunner`.60 The stock bundle ID belongs to another team and fails signing.613. `ios tunnel start --userspace` in the background. No sudo needed.624. `xcodebuild test-without-building -xctestrun <file> -destination id=<udid>` in63 the background. The log prints `ServerURLHere->http://<ip>:8100`.645. `ios forward 8100 8100`, then `curl localhost:8100/status`.6566Add mobile-mcp, pinned:6768```sh69CLAUDE_CONFIG_DIR=<config dir> command claude mcp add mobile-mcp -s user -- npx -y @mobilenext/mobile-mcp@<version>70```7172mobile-mcp finds real devices through go-ios and expects WebDriverAgent on port738100. Its tools load only in a new agent session.7475## Traps7677Each of these cost a cycle on a real iPhone running iOS 27.7879| Symptom | Cause | Fix |80|---|---|---|81| `Unable to log in with account ... login details were rejected` | Xcode's saved account session expired | The owner signs in again in Xcode > Settings > Accounts |82| `Unlock <name> to Continue` in the test log | The phone is locked | The owner unlocks it; the run continues by itself |83| `/wda/locked` is false but app launch fails with `could not be unlocked` | `/wda/locked` reports the screen is on, not that the passcode was entered | Test unlock by launching an app, as `iphone-wda wait` does |84| A Settings row is missing from the tree | Settings builds rows lazily, and `/wda/swipe` did not scroll it | Drag by coordinates (`/wda/dragfromtoforduration`) until the row appears |85| An alert covers the screen but `/alert/dismiss` says no alert is open | A system alert, such as an account password prompt, is outside the app's tree | Screenshot, then tap the button by point. Points are pixels divided by the screen scale |86| `App-prefs:` URL opens Settings > Apps | iOS 27 no longer routes those paths | Navigate by taps |87| Settings search finds no result for a page | Search does not index every page | Navigate by taps |88| A tap by label opened the wrong page | A label match hit a row in another list | Use exact labels, and check the navigation bar after each tap |89| `claude mcp add` wrote to another account's config | A `claude` shell function picked a different `CLAUDE_CONFIG_DIR` | Run `command claude` with `CLAUDE_CONFIG_DIR` set |90| `idevicescreenshot` fails with `Invalid service` | It needs a developer disk image it cannot mount | Use `xcrun devicectl device capture screenshot` |9192## Verify9394- `curl -s localhost:8100/status` shows `"ready" : true`.95- `iphone-wda open com.apple.Preferences` then `iphone-wda tree` prints the96 Settings rows.97- A screenshot shows the screen you expect.9899## Related skills100101- [`org-iphone-storage`](../org-iphone-storage/SKILL.md) uses this to read102 Settings > General > iPhone Storage.103- [`ios-agent-preview`](../ios-agent-preview/SKILL.md) covers simulators and104 installing your own app.105- [`macos-input-injection`](../macos-input-injection/SKILL.md) covers the106 iPhone Mirroring route.