Model or dataset
witchan/ios-mcp avatar
witchan/ios-mcp

iOS MCP puts 46 device-control tools on a jailbroken iPhone

iOS MCP: MCP management tool for jailbroken iPhones, enabling developers and AI agents to inspect and control devices.

693 stars123 forksObjective-CMIT

At a glance

What is it?
witchan/ios-mcp is a Theos tweak that turns a jailbroken iPhone into an MCP server, so Claude, Codex or Cursor can tap, type, install apps, read logs and run shell commands over the local network. Useful and unauthenticated in equal measure, and honest about both in its own security notes.
Who is it for?
Use iOS MCP when you have a jailbroken device you are willing to expose on a trusted network and you want an agent to drive a real screen rather than a simulator. Do not point it at a device holding accounts you cannot lose, and do not treat the port as private: there is no authentication, run_command takes any shell string, and the file tools work to the server process's own permissions.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 49 days ago.
What is it written in?
Mainly Objective-C, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • witchan/ios-mcp693 ★ · +50
Star history
Repository2026-09-112026-11-15
witchan/ios-mcp643693

50 Stars in the last 65 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

46 tools, grouped by what the agent is allowed to touch

The tool surface is organised by capability rather than by API, and the categories are a good map of what an agent can do to a phone. Touch gestures cover tap_screen, swipe_screen, long_press, double_tap and drag_and_drop, with path-based dragging. Physical buttons are simulated over HID: press_home, press_power, press_volume_up, press_volume_down, toggle_mute and wake_and_home, which also covers waking from a locked or dark screen. Text input splits three ways, clipboard fast input, per-character HID simulation and special keys. Screenshots come back as Base64 JPEG alongside screen size and orientation. App management is eight tools, from launch_app and kill_app to install_app, uninstall_app and queries for sandbox paths and entitlements. Accessibility work adds get_ui_elements, get_element_at_point, tap_element, wait_for_element, wait_for_disappear, ocr_screen and describe_screen. The tail is short and blunt: read and write the clipboard, list and read and write files, pull syslog and crash logs, set brightness and volume, read device info including jailbreak type, open a URL, and run_command.

Three jailbreak flavours, three package architectures

Installation is a table lookup. Rootful jailbreaks on iOS 13 through 18 use the iphoneos-arm package, rootless on iOS 15 through 18 use iphoneos-arm64, and roothide on iOS 15 through 18 uses iphoneos-arm64e. There are two install paths. The first is downloading the deb from the releases page and picking the row that matches the device, with two manual dependencies to satisfy first: mobilesubstrate/ElleKit and preferenceloader. The second is searching for iOS MCP inside Cydia or Sileo and letting the package manager resolve those dependencies. The Makefile targets arm64 and arm64e. The jailbreak package architecture label `iphoneos-arm` should not be assumed to describe a 32-bit executable slice: Apple requires 64-bit apps on iOS 11 and later. Check the actual package and jailbreak compatibility for the device before installing. The scheme is selected at build time through THEOS_PACKAGE_SCHEME, with roothide adding a define and its own library, and rootless adding its own define.

Port 8090 and the JSON that tells you it started

After installation the service needs one restart of SpringBoard, and then it can be checked from any browser on the network:

text
http://设备IP:8090/health

The placeholder in that address is written in Chinese in the documentation, which is a small reminder that the primary documentation is the Chinese README. A healthy device answers with a single JSON object:

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

That response is more useful than a plain ok, because it reports the protocol versions the server will speak, 2025-11-25 by default with 2025-06-18 and 2025-03-26 accepted, and it carries the build number, which is how you tell a stale tweak from the release you meant to install. Connecting a client is then a copy-and-paste step: open Settings, then iOS MCP, start the service, tap the button that copies and shares an MCP prompt snippet, and paste it into your agent's prompt. The settings screen follows the device language, showing Simplified Chinese, Traditional Chinese or English with no manual selector, and the screen also contains the QR code cell used for that handover.

Two OCR engines, and no automatic fallback between them

Screen reading has an engine switch that is easy to miss. Both ocr_screen and describe_screen with include_ocr set to true accept an optional engine parameter. Leave it out or pass paddleocr and you get offline PaddleOCR running on ONNX Runtime on the CPU. Pass vision and you get Apple Vision instead. Three details govern the choice. The setting applies to the current request only, so there is no global default to configure and no remembered preference. A failure does not switch engines, which means a caller has to catch the error and retry with the other value itself. And the two engines are not equivalent: on iOS 13, Vision defaults to recognising English only, while PaddleOCR handles Chinese, English and digits. For a Chinese-language screen, that difference decides whether the tap that follows lands on the right element. The build, the parameter examples and the validation notes live in docs/PADDLEOCR.md, and the Makefile runs Paddle in a separate process from SpringBoard so that OCR cannot take the tweak down with it.

No authentication, and one restricted root that is not sudo

The security notes are unusually direct, starting with the fact that the MCP service has no built-in authentication and is meant for a local network only. From there the exposure grows in steps. run_command executes arbitrary shell commands and is flagged as needing care. read_file, write_file and download_file reach any device path the server process itself can reach, and are placed at the same risk level. get_syslog reads live system logs from every app through a helper signed with the com.apple.private.logging.stream entitlement, so its output can contain sensitive data. Against that, mcp-root offers constrained escalation: package-internal tools only, restricted chmod and launchctl, id with no arguments, and dpkg limited to install, unpack, query, remove and purge against an absolute .deb path or a package id. The project states plainly that this is not a general sudo. One mitigation is built in: while the device is locked or the screen is off, the server intercepts interaction and write tools, including taps, swipes, text input, app launches and shell commands, and lets through only status queries, screenshots and the wake-and-recovery tools.

The tool table and the security notes count differently

Count the categories and they add up to exactly the 46 tools claimed: 5 touch gestures, 6 hardware buttons, 3 text input, 2 screenshot, 8 app management, 7 accessibility and element operations, 2 clipboard, 3 file system, 3 log, 4 brightness and volume, 1 device info, 1 URL and 1 shell. That total leaves no room for download_file, which appears only in the security notes as one of the three file tools. So either the table is missing an entry or the notes name a tool that no longer exists, and nothing in the documentation settles it. The same kind of drift shows up in install_app, which accepts .ipa, .tipa and .deb with case-insensitive extensions and installs a .tipa as an IPA, and requires anything still on your computer to be pushed to the device first through a POST /upload_file request whose returned device path is then passed to install_app. With v1.2.6, v1.2.7 and v1.2.8 published on 24, 26 and 27 September 2026, the documentation is three builds old at minimum.

Private frameworks, a hardcoded SDK path and a WeChat community

The source tree is flat and tells you how the project is built. Tweak.x plus 21 Objective-C sources compile into one tweak, ios-mcp, and a separate preference bundle, iosmcpprefs, installs into /Library/PreferenceBundles and links the Preferences private framework. The build sets ARC and links IOKit, UIKit, CoreGraphics, QuartzCore, MobileCoreServices, AVFoundation, Security and Vision. Two details will bite anyone rebuilding it. Private API headers sit at the repository root, AXPrivate.h, IOHIDPrivate.h and SpringBoardPrivate.h, and the accessibility bridge is built on top of them. And the bundle's linker flags hardcode a path into the Theos SDK, $(THEOS)/sdks/iPhoneOS16.5.sdk/System/Library/PrivateFrameworks, so a machine with a different SDK version under Theos will not find it. Support and community run through WeChat rather than a public forum: eight groups are described, seven of them full, with the eighth open, and entry is via the handle witchan028 or a public account, with an email address as the fallback. The code is MIT with a NOTICE file for attribution and disclaimers, and third-party components including AppSync Unified, appinst, ldid, OpenSSL, libplist and libzip carry their own licences.

Editorial conclusion

Use iOS MCP when you have a jailbroken device you are willing to expose on a trusted network and you want an agent to drive a real screen rather than a simulator. Do not point it at a device holding accounts you cannot lose, and do not treat the port as private: there is no authentication, run_command takes any shell string, and the file tools work to the server process's own permissions. Before you install, check the jailbreak type against the architecture table, read the NOTICE terms, and pin a release rather than tracking the tip, since three releases landed in four days.

Frequently asked questions

What does the iOS MCP server need before it will run?

A jailbroken iOS device. Rootful jailbreaks are supported on iOS 13 to 18 with the iphoneos-arm package, rootless on iOS 15 to 18 with iphoneos-arm64, and roothide on iOS 15 to 18 with iphoneos-arm64e. Install the deb from the releases page or search for iOS MCP in Cydia or Sileo, restart SpringBoard once, and check http://<device-ip>:8090/health.

What can the 46 tools in iOS MCP actually do?

They cover screen gestures, simulated hardware buttons over HID, clipboard and per-character text input, Base64 JPEG screenshots, app management including install_app and uninstall_app, accessibility queries and taps, screen OCR, clipboard access, file listing and read and write, syslog and crash logs, brightness and volume, device info, URL opening, and run_command for arbitrary shell commands.

Is it safe to expose the iOS MCP server to a network?

Not beyond a trusted local network. The service has no built-in authentication, run_command accepts any shell string, read_file and write_file reach whatever the server process can reach, and get_syslog can return sensitive data from every app through a helper signed with the com.apple.private.logging.stream entitlement. While the device is locked, interaction and write tools are blocked and only status queries, screenshots and wake tools pass.

How do I install an app on a device with iOS MCP?

install_app accepts .ipa, .tipa and .deb files with case-insensitive extensions, and a .tipa is installed as an IPA. Anything still sitting on your computer has to be uploaded to the device first with a POST /upload_file request, and the device path that comes back is what you pass to install_app.

Which OCR engine does iOS MCP use for screen reading?

ocr_screen and describe_screen with include_ocr set to true take an optional engine parameter. Omit it or pass paddleocr for offline PaddleOCR on ONNX Runtime CPU, or pass vision for Apple Vision. The choice applies to that request only, a failure does not fall back to the other engine, Vision defaults to English on iOS 13, and PaddleOCR handles Chinese, English and digits.

Official sources

  1. Issues
  2. License: MIT
  3. README
  4. Releases
  5. witchan/ios-mcp on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/witchan-ios-mcp.svg)](https://hysenlabs.com/projects/witchan-ios-mcp)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/witchan-ios-mcp.svg)](https://hysenlabs.com/projects/witchan-ios-mcp)

Was this useful?