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.

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: iphone-mcp

Requirements

• macOS with Xcode 16+ 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: if neither IOS_DEVICE_MCP_DEVICE nor a tool's device argument is set, the server only picks a device that is physically connected over USB. It never picks a Wi-Fi-only device implicitly.

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.

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.

• 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.

• No lock/unlock or Face ID simulation.

License

MIT. See LICENSE.