iphone-mcp
This MCP server gives an AI agent eyes and hands on a real, physical iPhone — it can see the screen, read the UI, and tap, type, swipe and launch apps over USB or Wi-Fi.
Manage the agent connection – start/stop WebDriverAgent, check status (connection type, screen size, lock state, foreground app), and keep the screen from auto-locking.
See the screen – take screenshots scaled to iOS points (image pixels = tap coordinates) and dump the visible UI tree with labels, positions and sizes.
Touch and gesture input – tap, double-tap, long-press at coordinates, or tap an element by its text; swipe, scroll in any direction, and pinch-zoom.
Text and hardware input – type into the focused field (optionally pressing Return), and press Home, volume up or volume down.
Device control – lock the iPhone or wake/unlock it (passcode-free only), and wait for text to appear or disappear instead of guessing delays.
App and link control – list installed apps, launch or terminate apps by name or bundle ID, and open URLs or deep links (https, maps:, tel:, custom schemes).
Gives agents eyes and hands on a real iPhone: screenshots scaled to iOS points and a compact UI tree with labelled elements, plus tools to tap (by coordinate or by text), double-tap, long-press, swipe, scroll, type, press Home/volume buttons, lock or wake the device, keep the screen from auto-locking, list/launch/terminate apps, and open URLs or deep links.
An MCP server that gives Claude Code, OpenAI Codex and any other MCP clienteyes and hands on a real, physical iPhone – over a cable or Wi-Fi.
Quick start · Tools · Wi-Fi · Linux & Windows · Safety · Troubleshooting · Sponsor ❤
✨ Highlights
👀 Sees the screen
Screenshots come scaled to iOS points, so every pixel the model sees is a coordinate it can tap. The UI tree turns the screen into compact text with labels and positions. It is faster, cheaper and more precise than pixels.
👆 Acts like a person
Tap, double-tap, long-press, tap by text, swipe, scroll, pinch-zoom, type, press Home and the volume buttons, and wait for text to appear instead of guessing delays. It can also launch apps by name ("Settings", "Einstellungen") and open URLs and deep links.
📶 Cable or Wi-Fi
It picks the best route on its own: the Xcode tunnel, then usbmux, then the iPhone's last known Wi-Fi IP. If the cable drops out, it reconnects over Wi-Fi.
🔆 Stays awake
While an agent is connected, the screen doesn't auto-lock. It sends an invisible touch just outside the display, and no settings are changed. This works even in Low Power Mode, where Auto-Lock is fixed at 30 s.
🔐 Your device, your signature
No jailbreak, no third-party cloud. WebDriverAgent is built and signed with your own Apple ID (a free one works), and all traffic stays between your computer and your phone.
🐧 Not only macOS
On Linux and Windows, WebDriverAgent starts without Xcode through pymobiledevice3's root-free tunnel. iphone-mcp doctor checks the whole chain.
Related MCP server: Zeptap
🚀 Quick start
You need: uv, an iPhone with an Apple ID, and a Mac with Xcode (for Linux / Windows see below).
1 · Prepare the iPhone (once)
Connect it by cable, unlock it and tap Trust.
Settings → Privacy & Security → Developer Mode → on (the phone restarts).
Settings → Developer → Enable UI Automation → on.
2 · Build WebDriverAgent (once, and again after Xcode updates)
uvx iphone-mcp doctor # checks Xcode, signing, iPhone
uvx iphone-mcp setup # builds & installs WebDriverAgent, signed with your Apple ID3 · Add it to your agent
claude mcp add iphone -s user -- uvx iphone-mcp~/.codex/config.toml
[mcp_servers.iphone]
command = "uvx"
args = ["iphone-mcp"]
tool_timeout_sec = 180 # starting the agent can take a minute{
"mcpServers": {
"iphone": { "command": "uvx", "args": ["iphone-mcp"] }
}
}git clone https://github.com/DamienDrash/iphone-mcp.git && cd iphone-mcp
uv run iphone-mcp setup
claude mcp add iphone -s user -- uv --directory "$PWD" run iphone-mcp4 · Ask, for example:
“Start the iPhone agent, open Settings and tell me which Wi-Fi I'm on.”
“Open the App Store, search for ‘Duolingo’ and show me the rating – don't install anything.”
“Test the sign-up flow of my TestFlight build and screenshot every step.”
🧠 How it works
flowchart LR
A["Claude Code · Codex<br/>any MCP client"] -- stdio --> B["iphone-mcp"]
B -- "HTTP :8100<br/>Xcode tunnel · usbmux · Wi-Fi IP" --> C["WebDriverAgent<br/>on the iPhone"]
B -. "launch: xcodebuild (macOS)<br/>or pymobiledevice3 (any OS)" .-> C
C -- XCUITest --> D["iOS UI"]WebDriverAgent is the XCUITest-based agent that Appium also uses. It runs as a test runner on the iPhone and exposes the UI over HTTP. iphone-mcp:
builds or installs it,
starts it with
xcodebuildor with pymobiledevice3's XCUITest service,keeps one connection alive across cable and Wi-Fi,
turns it all into a handful of tools a model can use well.
🧰 Tools
Tool | What it does |
| Start / stop WebDriverAgent (cable or Wi-Fi) |
| Connection, screen size, lock state, keep-awake, foreground app |
| Screenshot scaled to iOS points – image pixels = tap coordinates |
| Visible elements with text and center point |
| Wait until a text appears (or disappears) – no guessing of delays |
| Tap, double-tap or long-press at coordinates |
| Tap the element showing a given text |
| Swipe / scroll in any direction |
| Two-finger pinch to zoom in or out |
| Type into the focused field, optionally press Return |
| Home, volume up, volume down |
| Lock, or wake/unlock (without passcode) |
| Turn the no-auto-lock behaviour on or off |
| List, launch (name or bundle ID), terminate apps |
| Open a URL or deep link |
📶 Wi-Fi
Connect the iPhone by cable once. In Xcode open Window → Devices and Simulators, select the iPhone and tick Connect via network.
Put the iPhone and your Mac on the same Wi-Fi. The iPhone must be on Wi-Fi, not only on mobile data.
Unplug.
uvx iphone-mcp doctorshould now sayconnected via Wi-Fi.
iphone-mcp uses the tunnel that Xcode itself keeps to the phone. That tunnel works the same over cable and Wi-Fi, so a flaky cable is not a problem once Wi-Fi is set up.
🔆 Screen lock
Situation | What happens |
Agent connected | Keep-awake stops the screen from auto-locking. Turn it off with |
Phone already locked | The tools say so. The agent can wake the screen; you enter the passcode or use Face ID – the agent can't, by design. |
Starting the agent | Needs an unlocked iPhone (Xcode's rule). The agent is told to ask you, and the start continues by itself once you unlock. |
🐧 Linux & Windows
Everything except building WebDriverAgent works without a Mac. iphone-mcp starts WebDriverAgent through pymobiledevice3's XCUITest service and its root-free userspace tunnel (iOS 17.4+), over USB or Wi-Fi.
uvx iphone-mcp setup --prebuilt # downloads Appium's prebuilt, unsigned WebDriverAgent (.ipa)
# sign it with your Apple ID – Sideloadly (Windows, free Apple ID) or zsign (Linux, paid account)
uvx iphone-mcp setup --ipa signed.ipa # installs it over USB and remembers its bundle ID
uvx iphone-mcp start # or let your agent call iphone_start_agentmacOS | Linux | Windows | |
Build & sign WebDriverAgent | ✅ | ➖ sign the prebuilt | ➖ sign the prebuilt |
Install WebDriverAgent | ✅ | ✅ | ✅ |
Start WebDriverAgent | ✅ Xcode or pymobiledevice3 | ✅ pymobiledevice3 | ✅ pymobiledevice3 |
Control over USB | ✅ | ✅ needs | ✅ needs Apple Devices / iTunes |
Control over Wi-Fi | ✅ | ✅ | ✅ |
You can also leave WebDriverAgent running from a Mac and drive it from anywhere on the network:
IPHONE_MCP_WDA_URL=http://<iphone-ip>:8100 uvx iphone-mcpWhat is tested so far: the no-Xcode path – installing with setup --ipa and starting through
pymobiledevice3 – on macOS against a real iPhone (iOS 26.6) over usbmux Wi-Fi sync.
Not tested yet: USB, the pure RemotePairing Wi-Fi mode (IPHONE_MCP_MODE=wifi) and real Linux / Windows
machines. Reports are very welcome – please open an issue with the output of iphone-mcp doctor.
⌨️ Command line
Command | |
| Run the MCP server on stdio (what your client starts) |
| Check Xcode / signing / iPhone / connection |
| Build & install WebDriverAgent with Xcode |
| Without Xcode: download the prebuilt app / install a signed one |
| Start / stop WebDriverAgent without an MCP client |
⚙️ Configuration
Environment variable | Meaning |
| Pick a device when several iPhones are connected |
|
|
| Fixed WebDriverAgent address, e.g. |
|
|
|
|
| Signing team and bundle ID for |
| Bundle ID of an installed WebDriverAgent runner (no-Xcode launch) |
| WebDriverAgent release to build or download (default: a tested one) |
iphone-mcp writes files only to these places, never to your project:
What | macOS | Linux / Windows |
Config |
|
|
WebDriverAgent source and builds |
|
|
Logs |
|
|
🛡️ Safety
This gives an AI agent hands on your real phone, with your accounts, messages and payment methods.
The server tells the agent to ask before anything with real-world effect: sending messages, purchases, payments, deleting data, changing account or security settings. Watch what it does anyway, and keep your client's tool approvals on.
iphone-mcp never types passwords or passcodes.
While WebDriverAgent runs, it listens on port 8100 on the iPhone without authentication. Use trusted networks only, and stop it when you're done (
iphone-mcp stop).
See SECURITY.md for how to report vulnerabilities.
🩺 Troubleshooting
Symptom | Fix |
| The iPhone isn't connected right now – replug, unlock, run |
“Unlock … to Continue” / “device is locked” | Unlock the iPhone; the start continues by itself. |
| Wi-Fi isn't set up – see Wi-Fi. Is the iPhone on the same Wi-Fi as the computer? |
Signing errors during | Xcode → Settings → Accounts: sign in. Use |
Worked yesterday, not today (free Apple ID) | The signature expired after 7 days – run |
Runner exits immediately | Settings → Developer → Enable UI Automation, and trust the developer app under General → VPN & Device Management. |
Logs: ~/Library/Logs/iphone-mcp/wda.log (runtime) and build.log (setup).
🤝 Contributing
Issues and pull requests are welcome – see CONTRIBUTING.md. Run the checks with:
uv sync && uv run pytest && uv run ruff check . && uv run ruff format --check .👤 Author
Built by Damien Frigewski – @DamienDrash.
💖 Support the project
iphone-mcp is free and open source, and it stays that way. If it saves you time, you can support its development through GitHub Sponsors. Monthly and one-time options are available, and every amount helps. Sponsors get nothing extra in the software; it's simply a thank-you that keeps the work going.
A ⭐ on GitHub helps too – it makes iphone-mcp easier for others to find.
📄 License & credits
GPL-3.0-or-later. The GPL follows from pymobiledevice3, which iphone-mcp builds on.
WebDriverAgent (BSD-3-Clause, © Meta Platforms and Appium contributors) is downloaded and built or installed on your own machine; it is not redistributed here.
Not affiliated with Apple. iPhone, iOS and Xcode are trademarks of Apple Inc.
Available Tools
19 toolsiphone_close_appADestructiveIdempotent
Force-quit an app, like swiping it away in the app switcher.
Use it to reset an app to a fresh start or to stop something running. Unsaved input in that app (for
example a half-written message) can be lost, so prefer iphone_press_button('home') to just leave it.Inputs: app (required). Returns: result
iphone_keep_awakeAIdempotent
Turn the no-auto-lock behaviour on or off for this session. It is on by default.
While on, an invisible touch just outside the screen is sent every 10 s, which iOS counts as activity;
no settings are changed and it ends with the session. Turn it off if the user wants the phone to lock.
It cannot unlock a phone that is already locked – use iphone_lock for that.Inputs: enabled (required). Returns: result
iphone_launch_appAIdempotent
Open an app, or bring it to the front if it is already running (its state is kept).
Faster and more reliable than finding and tapping its icon on the home screen. To start an app fresh,
call iphone_close_app first. To open a specific page or link inside an app, use iphone_open_url.Inputs: app (required). Returns: result
iphone_list_appsARead-onlyIdempotent
List the apps installed on the iPhone as 'Name — bundle ID' lines, sorted by name.
Use it to find the exact bundle ID or name for iphone_launch_app / iphone_close_app when a name is
ambiguous or not found. Needs the cable or Wi-Fi sync; otherwise it lists the built-in Apple apps it
knows. Reads only.Inputs: filter. Returns: result
iphone_lockAIdempotent
Lock the iPhone, or wake and unlock it.
'unlock' only completes on phones without a passcode; with a passcode or Face ID it wakes the screen
and reports that the user must unlock – never try to enter a passcode. Use iphone_status to see the
current lock state and iphone_keep_awake to prevent auto-lock.Inputs: action (required). Returns: result
iphone_open_urlA
Open a web page in Safari or a deep link in the app that handles it.
Use it to jump straight to a page or screen instead of navigating by taps. Links with tel:, sms:,
mailto: or payment schemes start real actions or drafts on the phone – ask the user first. iOS may show
a confirmation dialog; check with iphone_ui_tree afterwards.Inputs: url (required). Returns: result
iphone_pinchA
Two-finger pinch gesture to zoom in or out, e.g. in Maps, Photos or a web page.
Use it only where content is zoomable; elsewhere it usually has no effect. Single-finger gestures are
covered by iphone_tap, iphone_swipe and iphone_scroll.Inputs: scale (required), x, y. Returns: result
iphone_press_buttonA
Press a hardware button of the iPhone.
iPhones have no back button: to go back inside an app, tap its back button (often top left, see
iphone_ui_tree). To leave an app use 'home'; to quit it completely use iphone_close_app; to lock the
screen use iphone_lock.Inputs: button (required). Returns: result
iphone_screenshotARead-onlyIdempotent
Capture the current iPhone screen as a JPEG image scaled to iOS points, plus its size.
Because the image is in points, any pixel position in it can be passed unchanged to iphone_tap or
iphone_swipe. Use it to see visual content (images, colours, layout, games). To find buttons or read
text, iphone_ui_tree is cheaper and gives exact positions. Reads only; adds a note if the phone is locked.Inputs: quality.
iphone_scrollA
Scroll the content in the middle of the screen in a direction.
Use it to reach items outside the visible area of lists, pages and carousels, then call iphone_ui_tree
again. It starts in the screen center, so it never triggers system edge gestures; for exact drags use
iphone_swipe.Inputs: direction (required), amount. Returns: result
iphone_start_agentAIdempotent
Start WebDriverAgent on the iPhone and connect to it – required before any other iphone_* action.
Call it when iphone_status or another tool reports no connection. It is safe to call again: if the
agent already runs it just reports the connection. Starting takes 10–90 s, works over cable or Wi-Fi
and needs the iPhone unlocked; if it is locked, the result says so and the user must unlock it.
Returns the connection route on success or a concrete reason on failure.Inputs: no named parameters. Returns: result
iphone_statusARead-onlyIdempotent
Report the iPhone connection and state: device and iOS version, connection route (USB or Wi-Fi), screen size in points, whether it is locked, whether keep-awake is on, and the foreground app.
Use it first in a session and whenever an action fails, to decide whether to call iphone_start_agent
(no connection) or ask the user to unlock (locked). Reads only; changes nothing on the phone.Inputs: no named parameters. Returns: result
iphone_stop_agentAIdempotent
Stop WebDriverAgent on the iPhone and close the connection.
Use it when the session is finished, so the automation port on the phone is no longer open. Afterwards
every other iphone_* tool fails until iphone_start_agent is called again. Leaves apps and data untouched.Inputs: no named parameters. Returns: result
iphone_swipeA
Drag one finger from a start point to an end point.
Use it for precise drags: sliders, reordering, swiping a cell to reveal actions, pulling down the
notification area or a sheet. For plain scrolling of a list or page, iphone_scroll is simpler.
Swipes starting at the very bottom or top edge trigger iOS system gestures (home, notifications).Inputs: x1 (required), x2 (required), y1 (required), y2 (required), +1 more. Returns: result
iphone_tapA
Touch the screen at a coordinate: single tap, double tap or long press.
Use it when you know the position – from iphone_ui_tree (center point) or iphone_screenshot (pixel =
point). To hit an element by its visible text, iphone_tap_text is more robust. The touch acts on
whatever is at that point, like a finger would; it does not wait for the app to finish reacting, so
look again (or call iphone_wait_for) before the next step.Inputs: x (required), y (required), gesture, hold_seconds. Returns: result
iphone_tap_textA
Find a visible element by its text and tap its center.
Prefer this over iphone_tap for buttons, cells and links with a label: it does not depend on layout or
screen size. If nothing matches, it says so and taps nothing; with several matches it reports how many
there are so you can pick another with `index`. Like a finger tap, the effect depends on the element.Inputs: text (required), exact, index. Returns: result
iphone_typeA
Type text into the text field that currently has keyboard focus.
Tap the field first (iphone_tap_text or iphone_tap) so the keyboard is open; without a focused field
the call fails. Text is appended at the cursor, not replacing existing content. Never use it for
passwords or passcodes – ask the user to enter those.Inputs: text (required), submit. Returns: result
iphone_ui_treeARead-onlyIdempotent
List the visible UI elements of the current screen as text, one per line: [Type] "label" value=… @(center x,center y) width×height, indented by nesting, all in iOS points.
Prefer this over iphone_screenshot to find buttons, fields and text and to read values: it is cheaper
and positions are exact. Pass the center point to iphone_tap, or use iphone_tap_text with the label.
Reads only; adds a note if the phone is locked.Inputs: max_lines. Returns: result
iphone_wait_forARead-onlyIdempotent
Wait until an element with the given text appears on screen (or disappears with gone=true).
Use it after an action that triggers loading, navigation or an animation, instead of guessing a delay or taking repeated screenshots. Polls about twice a second and returns as soon as the condition holds, with the element's position, or reports a timeout. Reads only.
Inputs: text (required), gone, exact, timeout. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 19 tools
The tools are cleanly separated by resource and action: session lifecycle, screen reading, gestures, text input, app control, and device locking. Overlaps such as tap vs tap_text, swipe vs scroll, and screenshot vs ui_tree are explicitly resolved in descriptions, so an agent can choose confidently.
All 19 tools use the iphone_ prefix and snake_case, yielding a predictable namespace. The only minor variation is that a few are noun-style read operations (iphone_status, iphone_screenshot, iphone_ui_tree) while most are verb-led, but the convention remains consistent and readable.
19 tools is slightly above the typical sweet spot but justified for a device-automation surface. Each tool covers a distinct capability, and no obvious redundant wrappers inflate the count.
Core lifecycle, observation, gesture, text-entry, app, and URL operations are covered, giving no major dead ends for UI automation. Minor gaps remain around clearing/replacing text, device settings, notifications, or advanced multi-touch, but these are outside the apparent scope.
Maintenance
Related MCP Connectors
Let your AI agent control real iPhones: screenshots, tap, swipe, type and open apps.
Cloud iPhones and Macs with Xcode for AI agents: build, run and test iOS apps, use the screen.
Drive real devices from your AI Coding tool. Embed a client SDK (Unity, Godot, Flutter, iOS/macOS, Android, React Native, Web) in your app, then capture screenshots, traverse the UI tree, inject taps and key events, and run automated test tasks on the physical device over a secure relay.
iMessage for AI agents, from your iPhone. No Mac needed, and you choose which chats they read.
Related MCP Servers
- FlicenseAqualityAmaintenanceControl a real iPhone or iOS Simulator through a macOS daemon and XCTest runner over USB or Wi-Fi: read screen text, tap, type, swipe, inspect logs and replay flows with explicit outcomes. Browser sandbox: use readonly to inspect 12 preloaded flows without a phone. Reuse an existing sandbox from MCP Deployments, or delete it before starting another. Device control needs your Mac and iPhone.643505-
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to operate a real iPhone from a Mac by reading the screen over USB and sending taps, swipes, typing, and app launches over Bluetooth, with every action returning a fresh screenshot so the agent can verify its work. Runs as a local MCP server, so agents can test iOS apps on physical devices and automate everyday phone tasks.40 npm10MIT
- AlicenseBqualityFmaintenanceEnables AI agents to see and operate a real USB-connected iPhone from a Linux Docker host — taking screenshots with region zoom, reading the element tree, tapping, swiping, long-pressing, typing text, pressing hardware buttons, listing/launching/terminating apps, and opening URLs. Automatically recovers from replugs and crashes, re-signs its automation agent before expiry, and falls back to a signing-free HID path on newer iOS.13MIT
- AlicenseAqualityBmaintenanceLet AI agents operate a real USB-connected iPhone from Linux — no Mac, no jailbreak, no paid developer account. Screenshots, taps, swipes, text input, element tree and app control via WebDriverAgent, with CoreDevice HID fallback.1742MIT