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.
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.
| Env var | Purpose |
|---|
IOS_DEVICE_MCP_TEAM_ID | Required. Team used to sign the runner |
IOS_DEVICE_MCP_BUNDLE_PREFIX | Runner bundle ID prefix (default dev.iosdevicemcp.<team>) |
IOS_DEVICE_MCP_DEVICE | UDID or name of the device to use |
IOS_DEVICE_MCP_ALLOW_DEVICE_REGISTRATION | 1 lets the build register a new device in your team |
IOS_DEVICE_MCP_PORT | Driver port (default 22087) |
IOS_DEVICE_MCP_AUDIO_DEVICE | Mac mic name substring for recordings (default: first non-iPhone/iPad input) |
IOS_DEVICE_MCP_RECORDINGS_DIR | Where WAVs go (default .build/recordings) |
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.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
