ios-device-mcp

An MCP server that drives a real iPhone or iPad (not the simulator) over USB for app development testing. It can build and install your app, launch it with console log capture, read the accessibility tree, tap, swipe, type and take screenshots. It can also talk to Siri and press the Action button, so an agent can run your App Shortcuts and App Intents on the phone.

More about it: individuation.dev/projects/ios-device-mcp.

How it works

• devicectl (Xcode's CoreDevice CLI) lists devices and installs, uninstalls and launches apps.

• runner/ is a small XCUITest bundle whose single test never ends. It runs an HTTP server on the device (port 22087) and maps requests to XCUITest calls (XCUICoordinate.tap, typeText, snapshot(), XCUIScreen.screenshot()…).

• src/ is the Node MCP server. It builds the runner with xcodebuild build-for-testing, starts it with xcodebuild test-without-building, and reaches it through the device's CoreDevice tunnel address (fd…::1). The tunnel works over USB and Wi-Fi with no port forwarding.

The driver starts automatically the first time a UI tool runs, takes about 5–8 s to start, and stops when the MCP server exits.

Related MCP server: open_phone

Requirements

• macOS with Xcode 16+ (tested with Xcode 27.1) and xcodegen (brew install xcodegen); ffmpeg for audio recording (brew install ffmpeg)

• Node 20+

• An iPhone/iPad that is paired, has Developer Mode on, is unlocked, and is registered in your developer team

Setup

git clone <repo-url> ios-device-mcp && cd ios-device-mcp
npm install && npm run build

Your Team ID is in Xcode > Settings > Accounts (select the team), or on developer.apple.com under Membership. Then register the server with Claude Code for all your projects:

claude mcp add --scope user ios-device \
  -e IOS_DEVICE_MCP_TEAM_ID=<TEAMID> \
  -- node "$PWD/dist/index.js"

Other MCP clients: run node dist/index.js over stdio with the same env vars. See .mcp.example.json for a project-scoped config.

The pre-rename IPHONE_MCP_* names are still read as a fallback.

Device selection: every tool takes a device argument (UDID or name). Without one, a tool uses the device chosen with select_device, then IOS_DEVICE_MCP_DEVICE, then the one device physically connected over USB. It never picks a Wi-Fi-only device implicitly, and with several on USB it asks for a choice.

Several devices at once: each device gets its own driver, so you can drive two phones in one session by passing device per call, or select_device one and pass device only for the other. Runner builds for different devices share one build directory and run one after another.

First run on a device: iOS asks for the passcode to allow UI automation. Keep the device unlocked while the driver starts.

Agent skill (optional)

The repo also ships a skill that teaches your agent how to use these tools well: the build → launch → describe → act → verify loop, element IDs over coordinates, waiting instead of sleeping, and the device-safety rules. Install it with the skills CLI:

npx skills add ChrisThoma/ios-device-mcp

Or copy skills/ios-device-mcp into ~/.claude/skills/. The skill only guides the agent; the MCP server above is what does the work.

Tools

Text matching in tap_element tries exact label/ID/value matches first, then whole-word matches in short labels. Every result says which element was tapped. Give your app accessibility identifiers and match with id for the most reliable tests.

Testing Siri, App Shortcuts and the Action button

Tested on an iPhone 15 Pro Max with iOS 27.0.1 and Xcode 27.1, where the Action button was pressed as well. The Camera button hasn't been tried on a device yet.

The siri tool gives Siri a phrase as if it had been spoken and returns the text Siri shows. It really runs, so this tests the path from the phrase through your App Intent to what Siri says back:

siri text: "Check MyApp"
  → the text Siri shows, one line per element
siri tap: "Turn On"
  → taps a button or row Siri is showing
press_button name: "action"
  → runs what the Action button is set to

• Siri's own UI: use tap on siri. A coordinate tap goes to the app behind Siri and dismisses it.

• Timing: Siri has no finished signal, so the tool reads the screen after a fixed wait. Raise wait (default 6 s) for a slow intent.

• First run of an app's shortcuts: the "Turn on shortcuts with Siri?" prompt doesn't work after text sent this way. It fails with "Something went wrong", with the logs putting the failure inside Siri, before the app. Use Type to Siri once instead: double_tap the bottom edge of the screen, tap the "Ask Siri" field so the keyboard shows, type_text the phrase, then tap the send arrow at the field's right end by its coordinates in a screenshot. Return adds a new line, and while the keyboard is up Siri reports its buttons below the screen, so siri tap: "Submit" hits a key. When the prompt shows, use siri tap: "Turn On". After that, text sent with siri works.

• Action button: the tool presses it but doesn't change what it's set to. Choose the action in Settings first.

Known limitations

• Foreground app: detected from the last launched app, else by scanning installed apps' states, else SpringBoard.

• Taps go to the foreground app: coordinates are anchored to the app in front. Anchored to SpringBoard, a tap on an in-app alert button also reached the view behind the alert. A tap inside a system alert (permission prompt) is anchored to SpringBoard instead: anchored to the app, XCTest's interruption handling answered the alert itself, so "Don’t Allow" granted the permission.

• Home button: XCUIDevice.press(.home) is ignored on some iOS 26 builds, so the driver falls back to activating SpringBoard. The press takes about 2–3 s.

• Landscape: coordinates are screen points in the current orientation, and landscape has had little testing.

• Logs: os_log/Logger capture works like Xcode's console: the app is launched with OS_ACTIVITY_DT_MODE (and OS_ACTIVITY_MODE=debug), which mirrors its log messages to stderr. Only messages from the app's own process are captured, not from system daemons or extensions. Private values show in plain text. Lines show [category] but not the subsystem.

• Recording sync: recordings use ffmpeg (brew install ffmpeg), and the terminal needs microphone permission. Recording start is measured to about ±70 ms. XCUITest takes about 0.4–0.7 s to deliver a tap, so the result gives a window ("sent at … completed at …"), and in testing the sound always landed inside it.

• Volume: iOS has no API to set the volume, and the level an app can read goes stale. set_volume presses the buttons and reads SpringBoard's volume indicator to verify the level, so the indicator briefly shows on screen.

• Siri: phrases are sent as text, so this doesn't test how Siri hears them. Anything Siri can do happens for real, including sending messages.

• Camera button: press_button with camera hasn't been tried on a device yet. The Action button has, on an iPhone 15 Pro Max.

• No lock/unlock or Face ID simulation.

License

MIT. See LICENSE.