ios-control-mcp
Provides tools to control a real iPhone running iOS, including capturing screenshots, tapping and swiping, typing text, pressing hardware buttons, opening and listing apps, and waiting between operations.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ios-control-mcp open the Settings app on my iPhone and take a screenshot"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
ios-control-mcp
Control a real iPhone from an MCP client on macOS. Capture screenshots, tap and swipe, type text, press buttons, and open apps through Apple's CoreDevice services, using pymobiledevice3.
The server runs locally over stdio. It uses on-demand screenshots rather than a continuous mirror, and requires no companion iOS app. USB is preferred; Wi-Fi is available after pairing and enabling wireless connections.
Status: beta. Device services can change between iOS releases. Automated tests cover protocol handling and mocked device behavior; they do not establish compatibility with every iPhone or iOS version. See the hardware validation checklist before relying on a new setup.
Requirements
macOS, including the built-in
/usr/bin/sipsimage converter.Python 3.10 or newer. CI targets Python 3.10, 3.12, and 3.13.
An iPhone with iOS 17 or newer, paired with this Mac, unlocked, and with Developer Mode enabled under Settings → Privacy & Security.
Working developer services on the device. Depending on iOS and the host setup, developer disk image preparation may be necessary; consult the upstream device setup documentation.
The iOS version is a transport prerequisite, not a promise that all tools work on every supported OS release. Linux and Windows device control are not supported by this project.
Related MCP server: sim-mirror
Install
git clone https://github.com/als0m3/ios-control-mcp.git
cd ios-control-mcp
python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install .Connect the iPhone with a cable, unlock it, and accept the trust prompt if shown. Enable Developer Mode and complete any restart or confirmation requested by iOS.
Connect an MCP client
Add a stdio server to your client's MCP configuration, using the absolute path to the installed executable:
{
"mcpServers": {
"ios-control": {
"command": "/absolute/path/to/ios-control-mcp/.venv/bin/ios-control-mcp",
"args": [],
"env": {
"IOS_CONTROL_TRANSPORT": "usb"
}
}
}
}Configuration formats differ between clients; some also require "type": "stdio".
Restart or reload the client after editing its configuration. The equivalent
module entry point is .venv/bin/python -m ios_control_mcp.
Start with iphone_status, then iphone_screenshot. The process waits for
newline-delimited JSON-RPC input when launched directly in a terminal; it does
not open a window or provide an interactive command prompt.
Tools
All coordinates are normalized, from 0.0 to 1.0: the top-left corner is
(0, 0) and the center is (0.5, 0.5). Measure against a recent screenshot.
Pixel coordinates, incorrect types, unknown arguments, and values outside the
published limits are rejected before any device operation.
Tool | Arguments | Behavior |
| None | iOS version, build, model, available transports, tunnel state; omits the device name and UDID |
|
| Returns a JPEG resized to the requested width; falls back to PNG if conversion fails |
| Required | Touch and release; contact lasts at least 100 ms |
| Required | Interpolated drag; requested duration excludes contact and flush delays |
| Required | Printable ASCII, tab, and newline are typed with a US keyboard mapping. Any other text (accents, emoji, other scripts) is pasted: it is placed on the device pasteboard, Command-V is pressed, and the previous pasteboard is restored if it held text |
| Required |
|
| Required | Exact bundle ID, exact display name, or unique partial name; ambiguous matches are rejected |
| Optional | Lists app names and bundle IDs; filter matches either field |
| None | Every attached device: UDID, transports, iOS version, model, Developer Mode, wireless connections, and whether it meets the preconditions to be driven; opens no tunnel and omits device names |
|
| Allows or forbids network connections to the selected device; run once over USB |
|
| Waits before the next operation |
Example arguments:
{"x": 0.5, "y": 0.5}{"x": 0.5, "y": 0.75, "x1": 0.5, "y1": 0.25, "ms": 400}{"app": "com.apple.Preferences"}A swipe beginning at the bottom edge can trigger the Home gesture. For scrolling
inside an app, start at y < 0.9. Keyboard layout, orientation, lock state, and
system dialogs can affect input. Newline may submit a form; tab may move focus.
Opening an app does not request termination of an already running instance. Allow time for launch animations, then take another screenshot to verify the result. A successful tool response confirms the request completed, not that the screen reached the intended state.
Device selection and configuration
Environment variable | Meaning |
| Select one specific device. If it is absent, the call fails instead of controlling another device. |
|
|
| Base device-call timeout in seconds, from 1 to 300; default 60. Typing and swiping add a bounded duration allowance. |
With multiple devices attached, set IOS_CONTROL_UDID. With one device, the
server remembers its selection until restart. Keep actual UDIDs in local client
configuration, not in committed files or public issue reports.
Requests run sequentially. Screenshots and app listing can reconnect and retry once after a connection failure. Input and app launching are never automatically replayed. A timeout or connection error may mean an action partially completed; inspect the screen before retrying it. Client cancellation notifications are not processed during an in-flight call; configured timeouts bound device operations.
Wi-Fi
With only the intended iPhone attached by USB, enable wireless connections:
.venv/bin/python -m pymobiledevice3 lockdown wifi-connections onKeep the Mac and iPhone on the same trusted network. Unset
IOS_CONTROL_TRANSPORT for USB preference with network fallback, or set it to
wifi to require a network connection. The phone must remain unlocked and
reachable. To disable wireless connections, reconnect over USB and run the
command with off instead of on.
Privacy and security
This server can read the visible screen and send input to the foreground app. Only connect trusted MCP clients and keep their tool approval controls enabled for consequential actions. Screenshots can include messages, credentials, and other private content; the MCP client may send tool results to its model provider.
The server has no telemetry or HTTP listener. It sends tool results over local stdio and communicates with the paired device. Image conversion uses temporary files removed when conversion finishes normally; abrupt process termination can leave files behind. The dependency manages pairing records and may download developer support assets. Client logs and dependency diagnostics can contain private information. See SECURITY.md before sharing a report.
Troubleshooting
Symptom | What to check |
No iPhone found | Cable, unlock state, trust pairing, and Developer Mode. For Wi-Fi, check wireless pairing and the network. |
Selected device unavailable | Check |
Multiple devices found | Set |
Developer service or tunnel error | Confirm developer services are ready, check upstream setup requirements, and restart the client after fixing the connection. |
Input completes but nothing changes | Confirm focus, normalized coordinates, keyboard layout, and absence of a blocking system dialog. |
Pasted text does not appear | The focused field must accept pasting. Fields that block it, such as some password or code fields, stay empty. |
App name is ambiguous | Use the exact bundle ID returned by |
Device action times out | Inspect the current screen before retrying; the action may already have partly completed. |
Client cannot start the server | Check its absolute executable path and environment variables. Inspect stderr locally; redact before sharing. |
Development
See CONTRIBUTING.md for setup and checks, architecture for the transport design, and CHANGELOG.md for behavior changes.
License
The code in this repository is licensed under the MIT License. Dependencies retain their own licenses. In particular, pymobiledevice3 is GPL-3.0-or-later; the MIT license here does not relicense that dependency. Review third-party license obligations when redistributing a combined package.
This is an independent project, not affiliated with or endorsed by Apple.
Available Tools
11 toolsiphone_buttonB
Press a hardware button: home, lock, volume-up, volume-down, mute or siri.
Inputs: name (required).
iphone_list_appsC
List installed apps with their bundle identifiers.
Inputs: contains.
iphone_list_devicesA
List every attached device with its UDID, transports, iOS version, model and Developer Mode, and whether it meets the preconditions to be driven. Does not open a tunnel or select a device.
Inputs: no named parameters.
iphone_open_appA
Launch an app by display name or bundle identifier. Allow a couple of seconds before the next screenshot, as a cold start takes a moment.
Inputs: app (required).
iphone_screenshotB
Capture the iPhone screen and return the image. Taken on demand at the native resolution, then downscaled to max_width for transport.
Inputs: max_width.
iphone_statusA
Device information and link state: iOS version, model, and which transports are currently available.
Inputs: no named parameters.
iphone_swipeA
Drag from (x,y) to (x1,y1), normalised 0.0–1.0. Avoid starting at the very bottom edge: iOS reads that as a system gesture and leaves the app.
Inputs: x (required), y (required), x1 (required), y1 (required), +1 more.
iphone_tapA
Tap the screen once. Coordinates are NORMALISED from 0.0 to 1.0 (x=0 is the left edge, y=0 the top), never pixels.
Inputs: x (required), y (required), hold_ms.
iphone_typeA
Type text into the focused field. Printable ASCII is typed with a virtual keyboard; any other text (accents, emoji) is pasted through the device pasteboard, which is restored afterwards when it held text.
Inputs: text (required).
iphone_waitA
Pause, to let an animation settle before the next screenshot.
Inputs: ms.
iphone_wifi_connectionsA
Allow (or forbid) connecting to the selected device over the network. Run once while it is plugged in over USB.
Inputs: enabled.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Each tool maps to a distinct action on the device: capture, tap, swipe, type, button press, app launch, app listing, device listing, status, wait, and network toggle. The only mild overlap is iphone_status versus iphone_list_devices, but the descriptions make the split (current device info vs. enumerate all attached devices) clear enough. Gesture tools (tap/swipe/button) are well differentiated by input mode.
All 11 tools share a uniform iphone_ prefix and snake_case, which makes the set instantly scannable. The suffix convention mixes nouns (status, screenshot, button, wifi_connections) with verbs (tap, swipe, type, wait) and verb_noun (open_app, list_apps, list_devices), a minor inconsistency but still readable and predictable.
Eleven tools is a well-scoped surface for device control automation, with no obvious filler. Each tool covers a primitive the agent would otherwise have to compose awkwardly. The inclusion of iphone_wait and iphone_status shows deliberate scoping to real automation needs rather than padding.
Core interaction primitives (screenshot, tap, swipe, type, buttons, app launch) are present, but the surface lacks element/accessibility inspection, so the agent is blind coordinate-tapping with only screenshots to guide it, and there is no long-press, key-event (return/backspace), or pinch/zoom gesture. Notably, iphone_list_devices explicitly does not select a device and no select_device tool exists, while other tools reference a 'selected device', leaving a real workflow dead end.
Maintenance
Related MCP Connectors
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.
Let your AI agent control real iPhones: screenshots, tap, swipe, type and open apps.
Securely control paired computers with ReMCP.
Use a person's computer after they approve it there: files, Terminal, browser, local MCP.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceControl a real, physical iPhone from an MCP client, enabling tapping, swiping, typing, reading messages, and navigating apps via Apple's UI-automation channel.1 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables mirroring and controlling the iOS Simulator from MCP clients, providing a live viewer, agent cursor tracking, and token-efficient UI snapshots for automation.871 PyPI2Apache 2.0
- AlicenseNot gradedqualityCmaintenanceEnables compatible AI apps to observe and control a locally connected iPhone through stdio MCP tools for screenshots, taps, swipes, long presses, text entry, key and button presses, app listing, and app launching, all reusing the console's device session.GPL 3.0
- AlicenseNot gradedqualityCmaintenanceEnables MCP-capable agents to control the macOS mouse and keyboard using screenshots and Quartz-based input events, including app switching, clicks, scrolling, text entry, shortcuts, and action-triggered screenshots.3MIT