iOS MCP: a Model Context Protocol server that runs on the jailbroken iPhone itself

The problem: MCP tooling assumes a host machine, not the phone

Most iOS automation stacks put the intelligence somewhere else. A desktop process drives the device over USB, or a WebDriverAgent runner is installed and controlled from a Mac. That arrangement works, but it means the phone is a peripheral. Anything the agent needs to observe has to travel back over the same link, and anything that requires device-local privileges has to be proxied. iOS MCP inverts this. The server runs on the jailbroken iPhone, and the MCP client (the README names Claude, Codex and Cursor) connects to it over the network. The device is the server. The audience is narrow and specific: iOS reverse engineers, jailbreak developers, and people building agents that need to poke at a real handset rather than a simulator. The README is written in Chinese with an English translation in README_EN.md, and the community section points at WeChat groups and a public account, which tells you where the project's users actually congregate.

46 tools, grouped by what they touch on the device

The tool list is the substance of the project, and it is worth reading as a map of the attack surface rather than as a feature list. Touch gestures cover tap_screen, swipe_screen, long_press, double_tap and drag_and_drop, with the README noting path-based dragging. Hardware keys are simulated through HID: press_home, press_power, volume up and down, toggle_mute, and wake_and_home for waking a locked or dark screen. Text entry splits three ways, and the distinction matters: input_text goes through the clipboard for speed, type_text simulates character-by-character HID input, and press_key handles special keys. Screenshots come back as Base64 JPEG, with get_screen_info returning dimensions and orientation. App management spans launch, kill, list, list running, frontmost, app info, install and uninstall, and the install path accepts both apps and DEB packages. The accessibility group is the most interesting for agent work: get_ui_elements returns the node tree, get_element_at_point does coordinate lookup, tap_element clicks by text or label, wait_for_element and wait_for_disappear handle timing, and ocr_screen and describe_screen aggregate what is on screen. Then there is clipboard read/write, file listing and read/write with binary support, syslog and crash log retrieval, brightness and volume, device info, URL opening, and run_command for arbitrary shell.

Installation is a deb, and the architecture has to match the jailbreak

This is not a pip install. The README gives a table mapping jailbreak type to system version and package architecture: rootful covers iOS 13 to 18 with iphoneos-arm, rootless covers iOS 15 to 18 with iphoneos-arm64, and roothide covers iOS 15 to 18 with iphoneos-arm64e. Picking the wrong architecture is the first way to waste an afternoon. Two installation routes exist. You can download the matching deb from the Releases page and install it manually, in which case the README lists mobilesubstrate or ElleKit and preferenceloader as dependencies you must satisfy yourself. Or you can search for iOS MCP in Cydia or Sileo and let the package manager resolve dependencies. After installation the README recommends restarting SpringBoard once, then checking the service from a browser at http://device-ip:8090/health. The documented healthy response is a JSON object with status ok, server ios-mcp, a version field matching the release (1.2.4 in the current example), protocolVersion 2025-11-25, and a supportedProtocolVersions array listing 2025-11-25, 2025-06-18 and 2025-03-26. Configuration happens in the device Settings app under iOS MCP, where you start the service and copy an MCP prompt fragment to paste into your AI client.

Protocol versioning is handled, and the server tells you which version it used

MCP has been moving, and this project tracks three revisions. The README states the default is 2025-11-25 with compatibility for 2025-06-18 and 2025-03-26, and that HTTP responses carry an MCP-Protocol-Version header. That header is the practical detail. When a client and server disagree about capabilities, the header is how you find out which revision the server actually negotiated rather than guessing from the client's configuration. It is a small thing, but it is the kind of small thing that separates a server someone maintains from a server someone published once. The health endpoint's supportedProtocolVersions array lets you check compatibility without opening a client at all, which is useful when you are debugging a connection that fails before any tool call happens.

The lock screen gate is the most thought-through part of the design

A remote control server on a phone has an obvious failure mode: an agent taps something it should not while the device is in a pocket or on a desk with the screen off. The README describes a gate for exactly this. When the device is locked or the screen is dark, the server blocks the interactive and write-class tools (taps, swipes, text input, app launch, shell) and allows only status queries, screenshots, and the wake-and-restore tools. That is a sensible split, and it is the kind of policy that is easy to state and hard to implement correctly. It is also the first thing I would test on real hardware, because the README describes the intent but does not enumerate which tools fall on which side of the line. If you plan to run unattended automation, the boundary between allowed and blocked is the boundary you are trusting.

No authentication, and the README says so plainly

The security section opens with the admission that the MCP service has no built-in authentication and recommends using it only on a local network. Everything else in that section follows from it. run_command executes arbitrary shell commands. read_file, write_file and download_file operate on any path within the MCP process's permissions, which the README explicitly rates as equivalent in risk to run_command. get_syslog reads live logs across all apps through a helper called mcp-logreader that carries the com.apple.private.logging.stream entitlement, and the README warns those logs may contain sensitive data. mcp-root is the interesting one: it provides limited root escalation, restricted to in-package tools, constrained chmod and launchctl calls, a no-argument id, and a narrow dpkg surface limited to -i, --install and --unpack with an absolute .deb path, plus -s, -r, --remove and --purge with a package id. The README is explicit that this is not a general sudo. Read that as a design statement: the author drew a line and documented where it sits, which is more than many jailbreak tools do.

Alternatives, and where the boundary actually falls

The obvious comparison is Appium with WebDriverAgent, which also drives a real iOS device and also exposes a structured element tree. The difference is architectural. WebDriverAgent runs as an app on the device but is driven by a host-side client over a USB or network link, and the automation logic lives on the host. iOS MCP puts the MCP server on the device and speaks the protocol directly to whatever agent you point at it. That removes the host from the loop, which is convenient, and it also removes the host as a place to enforce policy. A second comparison is libimobiledevice and the idevice* command line tools, which talk to the device over USB from a host and cover installation, file transfer, syslog and screenshots. Those tools are mature and do not require a jailbreak for the subset they support, but they do not expose a UI element tree or simulate touch at arbitrary coordinates. iOS MCP needs a jailbreak and gives you the touch layer. The trade is capability for a much larger trust surface.

Licence, third-party components, and what maintenance looks like

The project's own code is MIT, and the README states that using, modifying, distributing or merging the source, or substantial parts of it, requires keeping the copyright notice and licence text. A NOTICE file carries provenance and disclaimer, and the software ships AS IS with no warranty, with the author disclaiming liability for device faults, data loss, service interruption, account risk, system damage, security problems and commercial losses. That disclaimer is broader than most MIT boilerplate, which fits the category: this is software that runs with elevated privileges on a device you presumably care about. Third-party components are listed separately in THIRD_PARTY_NOTICES.md and include AppSync Unified, appinst, ldid, OpenSSL, libplist and libzip, each under its own licence. That matters if you plan to redistribute the deb, because the aggregate package is not simply MIT. On maintenance, the release cadence visible in the supplied material shows v1.2.2 in July 2026, v1.2.3 in late July, and v1.2.4 on 1 September 2026, so roughly monthly point releases. Each upgrade is a deb install and, per the README's own post-install steps, a SpringBoard restart. There is no stated migration path or configuration backup, so if you customize settings in the preference pane, assume you are re-entering them after a reinstall until you confirm otherwise.

Editorial conclusion

Adopt iOS MCP if you already run a jailbroken device on a network you control and want an AI agent to drive it through MCP rather than through a host-side toolchain. Do not adopt it if the device holds real accounts, if you cannot keep port 8090 off untrusted networks, or if you need the server to survive a reboot without manual intervention. Before trusting it with anything, verify three things on your own hardware: that http://device-ip:8090/health returns the documented JSON, that the lock-screen gating actually blocks a tap when the screen is off, and that mcp-root refuses a command outside its documented allowlist.

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. witchan/ios-mcp on GitHub