iphone-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| IPHONE_MCP_MODE | No | Connection mode: auto (default), usb or wifi. | |
| IPHONE_MCP_UDID | No | Pick a device when several iPhones are connected. | |
| IPHONE_MCP_TEAM_ID | No | Signing team ID for setup. | |
| IPHONE_MCP_WDA_REF | No | WebDriverAgent release to build or download (default: a tested one). | |
| IPHONE_MCP_WDA_URL | No | Fixed WebDriverAgent address, e.g. http://192.168.1.42:8100. | |
| IPHONE_MCP_LAUNCHER | No | Launcher to use: xcodebuild (default on macOS) or pymobiledevice3. | |
| IPHONE_MCP_BUNDLE_ID | No | Bundle ID for setup. | |
| IPHONE_MCP_KEEP_AWAKE | No | 1 (default) keeps the screen awake while connected, 0 turns it off. | |
| IPHONE_MCP_RUNNER_BUNDLE_ID | No | Bundle ID of an installed WebDriverAgent runner for no-Xcode launch. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Controls a real, physical iPhone. Coordinates are iOS points, not pixels: iphone_screenshot returns an image scaled to points, so a position in the image can be passed straight to iphone_tap. Typical loop: look (iphone_ui_tree is cheaper and more precise, iphone_screenshot for visuals) → act (iphone_tap_text / iphone_tap / iphone_swipe / iphone_type) → iphone_wait_for or look again. If there is no connection, call iphone_start_agent first. While connected, the screen is kept from auto-locking (iphone_keep_awake). If the iPhone is locked, a passcode must be entered by the user. Ask the user before anything with real-world effect (sending messages, purchases, payments, deleting data, changing account or security settings).
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| iphone_statusA | 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. |
| iphone_start_agentA | Start WebDriverAgent on the iPhone and connect to it – required before any other iphone_* action. |
| iphone_stop_agentA | Stop WebDriverAgent on the iPhone and close the connection. |
| iphone_keep_awakeA | Turn the no-auto-lock behaviour on or off for this session. It is on by default. |
| iphone_screenshotA | Capture the current iPhone screen as a JPEG image scaled to iOS points, plus its size. |
| iphone_ui_treeA | 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. |
| iphone_wait_forA | 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. |
| iphone_tapA | Touch the screen at a coordinate: single tap, double tap or long press. |
| iphone_tap_textA | Find a visible element by its text and tap its center. |
| iphone_swipeA | Drag one finger from a start point to an end point. |
| iphone_scrollA | Scroll the content in the middle of the screen in a direction. |
| iphone_pinchA | Two-finger pinch gesture to zoom in or out, e.g. in Maps, Photos or a web page. |
| iphone_typeA | Type text into the text field that currently has keyboard focus. |
| iphone_press_buttonA | Press a hardware button of the iPhone. |
| iphone_lockA | Lock the iPhone, or wake and unlock it. |
| iphone_list_appsA | List the apps installed on the iPhone as 'Name — bundle ID' lines, sorted by name. |
| iphone_launch_appA | Open an app, or bring it to the front if it is already running (its state is kept). |
| iphone_close_appA | Force-quit an app, like swiping it away in the app switcher. |
| iphone_open_urlA | Open a web page in Safari or a deep link in the app that handles it. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
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.