iOS MCP: an MCP server for jailbroken iPhones

What iOS MCP solves, and who it is for

Most iOS automation stops at the simulator. Real-device automation usually means Appium, XCTest or a private harness, and none of those give an AI agent a uniform tool surface. iOS MCP takes a different route: it is an MCP (Model Context Protocol) server that runs on the phone itself, inside a jailbroken iOS environment, and exposes the device's capabilities as MCP tools that any compatible client can call.

The README frames the audience directly: developers and AI agents that need to inspect and control iOS devices. In practice that means reverse engineers, QA engineers working on hardware-specific behaviour, and anyone building an agent workflow where the target is a physical iPhone rather than a simulator. The tool list is the strongest signal of intent. It spans touch gestures, HID key simulation, clipboard access, app install and uninstall, accessibility node trees, OCR, syslog, crash logs and shell execution. That is a reverse-engineering and debugging surface, not a consumer automation surface.

It is worth being blunt about the entry cost. The first requirement in the README is a jailbroken iOS device. Everything else, including the package architecture you download, follows from that.

How the tweak is put together

The repository is a Theos tweak, not an app. The Makefile defines TWEAK_NAME = ios-mcp and a preference bundle named iosmcpprefs, and the top-level entries are Objective-C manager classes compiled into the tweak: MCPServer.m, HIDManager.m, ScreenManager.m, AppManager.m, AccessibilityManager.m, TextInputManager.m, FileSystemManager.m, LogManager.m and OCRManager.m. Tweak.x is the injection point. The accessibility code is split further into MCPAXQueryContext, MCPAXRemoteContextResolver, MCPUIElementSerializer, MCPUIElementsFacade, MCPAXAttributeBridge and MCPAXNodeSource, which suggests the UI-element tools walk a private accessibility tree and resolve remote contexts rather than scraping pixels.

Supporting binaries sit alongside the tweak. mcp-logreader carries the com.apple.private.logging.stream entitlement and is what get_syslog uses to read logs across apps. mcp-root and mcp-roothelper provide the restricted privilege escalation the README describes. mcp-ldid is present for signing. The Makefile picks the package scheme at build time: rootless and roothide builds target iOS 15.0 and up, while the default rootful target is iOS 13.0. Roothide builds link against the roothide library and define MCP_ROOTHIDE; rootless builds define MCP_ROOTLESS.

The server speaks MCP over HTTP and, per the README, supports protocol version 2025-11-25 by default while remaining compatible with 2025-06-18 and 2025-03-26. Responses carry an MCP-Protocol-Version header. That version range is the practical compatibility contract for whatever client you point at it.

Installing iOS MCP from Sileo or Cydia

The README offers two install paths. The first is downloading a .deb from the release page, choosing the architecture that matches your jailbreak: iphoneos-arm for rootful on iOS 13 to 18, iphoneos-arm64 for rootless on iOS 15 to 18, and iphoneos-arm64e for roothide on iOS 15 to 18. Manual installs need mobilesubstrate or ElleKit plus preferenceloader already present. The second path is simply searching for iOS MCP in Cydia or Sileo and installing from there.

After installing, the README asks you to restart SpringBoard once and then check the health endpoint from a browser on the same network:

http://设备IP:8090/health

Replace the placeholder with the device's IP address. A working server returns JSON that includes the status, the server name, the version and the supported protocol versions:

{"status":"ok","server":"ios-mcp","version":"1.2.4","protocolVersion":"2025-11-25","supportedProtocolVersions":["2025-11-25","2025-06-18","2025-03-26"]}

If that JSON does not come back, the tweak is not running and no client configuration will help. Once it does, open Settings, go to iOS MCP, start the service, and tap the option the README labels as copying and sharing the MCP prompt snippet. Paste that snippet into your AI client's prompt. The README does not document a separate client-side config file, so the snippet is the intended integration path.

The lock screen gate and what it does not cover

One design decision deserves attention because it changes how you script against the device. When the screen is locked or off, the server blocks interactive and write-class tools: taps, swipes, text input, app launching and shell commands. It still allows status queries, screenshots, and the wake-and-home recovery path. So an agent that taps blindly will fail on a locked device, and the failure is a policy refusal rather than a coordinate miss. Any workflow has to wake the device first.

That gate is a usability safeguard, not a security boundary. The README is explicit that the MCP service has no built-in authentication and recommends using it only on a local network. There is no token, no pairing step and no TLS mentioned. Anyone who can reach port 8090 on that LAN can call the same 46 tools, including run_command, which the README describes as able to execute arbitrary shell commands. read_file, write_file and download_file carry the same risk level in the README's own words, and get_syslog can surface sensitive information from any app. Treat the network as the access control.

The mcp-root component is narrower than its name suggests. The README lists what it allows: package-internal tools, restricted chmod and launchctl, id with no arguments, and a constrained set of dpkg operations (install, unpack, remove, purge against absolute .deb paths or package IDs). It states plainly that this is not a general-purpose sudo. If your workflow needs arbitrary root, this is the wrong tool.

Where iOS MCP is the wrong choice

The jailbreak requirement eliminates most production use. A jailbroken device cannot be treated as representative of a stock device's behaviour, and many apps refuse to run on jailbroken hardware or alter their behaviour when they detect it. If your goal is to validate an app the way real users will run it, this tool measures the wrong environment.

There is also a real alternative worth naming. The iOS Simulator MCP approach, associated with joshuayoes/iOS simulator MCP, drives a simulator rather than a physical device. The difference in approach is fundamental: simulator tooling works through Apple's supported automation surfaces on a Mac, requires no jailbreak, and fits cleanly into CI. iOS MCP runs on the device as an injected tweak and reaches into private frameworks and entitlements that a simulator does not expose at all. If you need HID key simulation, cross-app syslog, crash log retrieval or real hardware behaviour, the simulator route cannot substitute. If you need repeatable, unprivileged automation of a build, it is the better fit and iOS MCP is overkill.

A second limitation is the documentation gap around failure modes. The README covers installation and the security model but says nothing about what happens when a tool call fails, whether the server recovers from SpringBoard restarts, or how to roll back to an earlier version. Those are the questions you will hit in the first week.

Licence, third-party components and upgrade cost

The project's own code is MIT licensed. The README notes that using, modifying, distributing or merging the source or substantial parts of it requires keeping the copyright notice and licence text, and points to a NOTICE file for provenance and disclaimers. The project is provided as is, with no warranty, and the README disclaims liability for device faults, data loss, service interruption, account risk, system damage, security problems or commercial loss arising from use.

MIT covers only the project's own code. Bundled third-party components, listed in the README as AppSync Unified, appinst, ldid, OpenSSL, libplist and libzip, carry their own licences, detailed in THIRD_PARTY_NOTICES.md. If you redistribute a built .deb rather than the source, that file is the one to read, and a lawyer is the one to ask about obligations that survive packaging.

Upgrade cost looks low from the release history. Versions v1.2.2, v1.2.3 and v1.2.4 landed between July and September 2026, with the most recent push on 2026-09-01. The protocol version range in the health response is the thing to re-check after each upgrade, because a client pinned to a specific MCP protocol version will stop working if support for it is dropped. The README does not describe an in-place upgrade path or a downgrade procedure, so keep the .deb you installed.

Editorial conclusion

Adopt iOS MCP if you already run a jailbroken iPhone on a network you control and you want an AI agent to drive real hardware: touch, app lifecycle, accessibility trees, syslog and screenshots through one MCP endpoint on port 8090. Skip it if the device is not jailbroken, if you need it reachable from the open internet, or if you cannot accept that run_command, read_file and write_file run with the MCP process's privileges and no authentication layer. Before wiring it into an agent, verify the /health response matches your installed version and confirm what the preference bundle's prompt snippet actually grants.

Frequently asked questions

Official sources

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