ios-mcp

# iOS MCP English | [中文](README.md) iOS MCP is a [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server running on a jailbroken iPhone, allowing AI agents (Claude, Codex, Cursor, etc.) to directly control iOS devices. ## Feature Overview | Category | Tool | Description | |------|------|------| | **Touch Gestures** | `tap_screen` `swipe_screen` `long_press` `double_tap` `drag_and_drop` | Precise screen coordinate operations, supporting path dragging | | **Hardware Keys** | `press_home` `press_power` `press_volume_up` `press_volume_down` `toggle_mute` `wake_and_home` | HID simulation of physical keys, lock screen/wake up | | **Text Input** | `input_text` `type_text` `press_key` | Quick input via clipboard / HID character-by-character simulation / special keys | | **Screenshots** | `screenshot` `get_screen_info` | Base64 JPEG screenshots, screen dimensions, and orientation | | **App Management** | `launch_app` `kill_app` `list_apps` `list_running_apps` `get_frontmost_app` `get_app_info` `install_app` `uninstall_app` | Launch/close apps, install/uninstall apps or DEBs, query app sandbox/container paths and entitlements | | **Accessibility / Element Operations** | `get_ui_elements` `get_element_at_point` `tap_element` `wait_for_element` `wait_for_disappear` `ocr_screen` `describe_screen` | Get UI node tree, coordinate element query, click elements by text/tag, wait for elements to appear or disappear, screen OCR text recognition and localization, aggregate screen snapshots | | **Clipboard** | `get_clipboard` `set_clipboard` | Read and write clipboard content | | **File System** | `list_dir` `read_file` `write_file` | Directory listing, file reading and writing (supporting text and binary) | | **Logs** | `get_syslog` `get_crash_logs` `read_crash_log` | Full app real-time system logs, crash log listing and reading | | **Device Control** | `get_brightness` `set_brightness` `get_volume` `set_volume` | Brightness, volume | | **Device Information** | `get_device_info` | Model, iOS version, battery, storage, memory, jailbreak method | | **URL** | `open_url` | Open links or URL schemes | | **Shell** | `run_command` | Execute shell commands | A total of **46** MCP tools, covering major scenarios for iOS device automation and reverse debugging. ## Running Requirements - Jailbroken iOS device ## Installation Instructions ### Supported Environments | Jailbreak Type | Supported System Versions | Package Architecture | |------|------|------| | `rootful` | iOS 13 - iOS 18 | `iphoneos-arm` | | `rootless` | iOS 15 - iOS 18 | `iphoneos-arm64` | | `roothide` | iOS 15 - iOS 18 | `iphoneos-arm64e` | ### Installation Methods #### Method 1: Download and Install from Release Page Please select the deb package corresponding to your jailbreak type and system architecture. Note the following dependencies when manually installing: - `mobilesubstrate/ElleKit` - `preferenceloader` #### Method 2: Install via Cydia / Sileo Search and install directly in the following package managers: - `Cydia` - `Sileo` Search name: - `iOS MCP` ### Post-Installation Checks 1. Restart `SpringBoard` once 2. Access via browser: ```text http://device IP:8090/health ``` 3. The following content indicates the service is started normally: ```json {"status":"ok","server":"ios-mcp","version":"1.2.2","protocolVersion":"2025-11-25","supportedProtocolVersions":["2025-11-25","2025-06-18","2025-03-26"]} ``` ## Usage After installation, open the device's "Settings" → "iOS MCP", start the service, and click "Copy MCP prompt fragment" to paste it into your AI prompt. <p align="center"> <img src="screenshots/settings.jpeg" alt="iOS MCP Settings" width="300"> </p> When downloading large files or binary files on the device, you can directly access the HTTP endpoint to avoid base64 truncation: ```bash curl 'http://device IP:8090/download_file?path=/var/mobile/...' -o output.bin ``` ## Security Notes - MCP service has no built-in authentication, recommended for use in local network environments only - MCP protocol supports `2025-11-25` by default and is compatible with `2025-06-18`, `2025-03-26`; HTTP response will return `MCP-Protocol-Version` - When the screen is locked or off, the server will intercept interactive/write tools like clicks, swipes, input, app launches, and shell commands, allowing only status queries, screenshots, and wake-up recovery tools - `run_command` tool can execute arbitrary shell commands, use with caution - `read_file` / `write_file` / `download_file` can read and write device paths within the MCP service process permissions, with the same risk level as `run_command`; use only in trusted networks - `get_syslog` reads full app real-time logs via `mcp-logreader` (signed with `com.apple.private.logging.stream` entitlement), which may contain sensitive information; use only in trusted networks - `mcp-root` provides limited root privilege escalation, allowing only package-internal tools, limited chmod/launchctl, parameterless id, and limited `dpkg -i|--install|--unpack <absolute path.deb>`, `dpkg -s|-r|--remove|--purge <package-id>`; it is not a universal sudo ## Community Communication `iOS MCP` has gathered many developers and users for continuous communication, and multiple WeChat discussion groups have been established. | WeChat Discussion Groups (6 groups open) | Official Account | |---|---| | 1 group: Full<br>2 group: Full<br>3 group: Full<br>4 group: Full<br>5 group: Full<br>6 group: Full<br>7 group: Open | `Mobile End Android and iOS Development Technology Sharing` | | <img src="https://raw.githubusercontent.com/witchan/Imgur/main/group6_qr.JPG" alt="iOS MCP WeChat 6 Group QR Code" width="260"> | <img src="prefs/Resources/wechat_qr.jpg" alt="Mobile End Android and iOS Development Technology Sharing Official Account QR Code" width="220"> | > If the 7th group QR code has expired, please add WeChat `witchan028` or follow the official account `Mobile End Android and iOS Development Technology Sharing` to get the latest group access method. Welcome to add WeChat or follow the official account to get the latest updates and group access methods. - WeChat: `witchan028` - Email: `witchan028@126.com` ## Author **witchan** ## License This project's code uses the MIT License, see [LICENSE](LICENSE) for details. When using, modifying, distributing, or merging this project's source code and significant parts, please retain the copyright notice and license text. [NOTICE](NOTICE) provides project sources and disclaimers. This project is provided "AS IS" without any express or implied warranties. The author disclaims all responsibility for device anomalies, data loss, service interruptions, account risks, system damage, security issues, business losses, or other direct/indirect impacts resulting from the use, modification, distribution, deployment, or operation of this project. Third-party components in the project (such as AppSync Unified, appinst, ldid, OpenSSL, libplist, libzip) follow their respective open-source licenses, see [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) for details.