Iphone

MCP (Model Context Protocol) server that gives Claude Code full control over a physical iPhone — via USB or WiFi (SSH).

Built for jailbroken devices with root access, Frida integration, and complete filesystem control. Also works on stock iPhones via USB with limited features.

---

Getting Started — Step by Step

Step 1: Install Host Dependencies (your PC/Mac)

You need Python 3.10+ and a few system packages.

Ubuntu/Debian:

sudo apt update
sudo apt install -y libimobiledevice-utils ideviceinstaller ifuse usbmuxd sshpass python3 python3-venv

macOS:

brew install libimobiledevice ideviceinstaller ifuse sshpass python3

Arch Linux:

sudo pacman -S libimobiledevice ideviceinstaller ifuse usbmuxd sshpass python

Step 2: Clone and Install the Server

git clone https://github.com/rafaelchriss/iphone-mcp-server.git
cd iphone-mcp-server
chmod +x setup.sh
./setup.sh

This creates a Python virtual environment and installs all dependencies (mcp, pymobiledevice3, pycrashreport).

Step 3: Connect via USB and Pair (First Time Only)

You MUST start with a USB cable for the initial setup.

1. Plug your iPhone into your computer with a USB cable
2. On the iPhone, tap Trust when the "Trust This Computer?" dialog appears
3. Verify the connection:

   idevice_id -l          # Should show your device UDID
   ideviceinfo | head -5  # Should show device info
   

4. If the device doesn't appear, restart usbmuxd:

   sudo systemctl restart usbmuxd   # Linux
   sudo launchctl stop com.apple.usbmuxd && sudo launchctl start com.apple.usbmuxd  # macOS
   

Step 4: Configure Claude Code

Add the MCP server to your Claude Code configuration (~/.claude/settings.json or project-level .mcp.json):

{
  "mcpServers": {
    "iphone": {
      "command": "/path/to/iphone-mcp-server/venv/bin/python3",
      "args": ["/path/to/iphone-mcp-server/server.py"],
      "env": {
        "IPHONE_UDID": "",
        "IPHONE_HOST": "",
        "IPHONE_SSH_PORT": "22",
        "IPHONE_SSH_PASS": "alpine",
        "IPHONE_SSH_USER": "root",
        "IPHONE_MODE": "auto"
      }
    }
  }
}

Replace /path/to/ with the actual path where you cloned the repo.

Step 5: Enable WiFi Mode (Jailbroken Devices)

Once you've paired via USB, you can go fully wireless. No cable needed after this.

5a. Requirements on iPhone

Your jailbroken iPhone needs these packages installed (via Sileo, Zebra, or apt):

• OpenSSH (openssh-server) — for SSH access
• Frida (re.frida.server) — for dynamic analysis tools (optional but recommended)
• tcpdump — for network capture (optional)

Install via terminal on the iPhone or through a package manager:

apt install openssh-server

5b. Find Your iPhone's WiFi IP

On the iPhone: Settings > Wi-Fi > tap your network > IP Address

Or from Claude Code (with USB still connected):

> What's my iPhone's WiFi IP?

5c. Update the Config with WiFi IP

Set IPHONE_HOST to your iPhone's WiFi IP address:

{
  "env": {
    "IPHONE_HOST": "192.168.1.174",
    "IPHONE_SSH_PORT": "22",
    "IPHONE_SSH_PASS": "alpine",
    "IPHONE_SSH_USER": "root",
    "IPHONE_MODE": "auto"
  }
}

5d. Test WiFi Connection

Unplug the USB cable and verify:

ssh [email protected]   # Default password: alpine

Or just ask Claude Code:

> Check the iPhone connection status

It should show wifi_ssh_available: true.

5e. Change the Default SSH Password!

The default jailbreak SSH password is alpine. Change it immediately:

ssh root@YOUR_IPHONE_IP
passwd
# Enter your new password twice

Then update IPHONE_SSH_PASS in your config.

Step 6: Unplug and Go Wireless

Once WiFi is configured:

1. Unplug the USB cable
2. Set IPHONE_MODE to "wifi" (or keep "auto" to use USB when available, WiFi otherwise)
3. Everything works wirelessly now — screenshots, shell access, file transfers, Frida, everything

---

Connection Modes

Mode	How	Cable Needed	Jailbreak Required	Full Filesystem
USB	libimobiledevice + pymobiledevice3	Yes	No	AFC sandbox only
WiFi	SSH over local network	No	Yes	Full root access
Auto (default)	USB first, WiFi fallback	Optional	For WiFi features	Best available

When to Use Each Mode

• auto (recommended): Best of both worlds. Uses USB when cable is connected, seamlessly falls back to WiFi/SSH when wireless. Zero configuration changes needed.
• usb: For stock (non-jailbroken) iPhones. Works for basic features: device info, screenshots, app listing, file access (within AFC sandbox).
• wifi: For fully wireless operation with jailbroken iPhones. Full root access, shell commands, Frida, filesystem — all over the air.

---

Tools (50+)

Device Information

Tool	USB	WiFi	Description
device_info	Y	Y	Full device details (model, iOS, serial, IMEI...)
device_name	Y	Y	Device name
device_list	Y	-	List connected iOS devices by UDID
battery_info	Y	-	Battery level and charging status
storage_info	Y	Y	Disk usage
network_info	Y	Y	WiFi/network configuration
wifi_ip	Y	Y	Current WiFi IP address
connection_status	Y	Y	Check USB/WiFi availability
system_info	Y	Y	System information overview

Screenshots

Tool	USB	WiFi	Description
screenshot	Y	Y	Capture screen — base64 PNG or save to file

App Management

Tool	USB	WiFi	Description
list_apps	Y	Y	List ALL installed apps — user, system, jailbreak (scans all directories including /cores/binpack/)
search_app	Y	Y	Search for a specific app by name or bundle ID
install_app	Y	Y	Install IPA file
uninstall_app	Y	Y	Remove app by bundle ID
launch_app	Y	Y	Start app via bundle ID or uiopen
kill_app	Y	Y	Kill running app
open_url	Y	Y	Open URLs / deep links
list_url_schemes	-	Y	Enumerate URL schemes for all apps
installed_tweaks_and_apps	-	Y	Combined view of tweaks + apps

File Access

Tool	USB	WiFi	Description
list_files	Y	Y	Browse directories (AFC sandbox via USB, full filesystem via WiFi)
pull_file	Y	Y	Download files from iPhone (AFC or SCP)
push_file	Y	Y	Upload files to iPhone (AFC or SCP)

SSH Shell (Jailbreak / WiFi)

Tool	WiFi	Description
shell	Y	Execute any command as root — full access
shell_interactive	Y	Run multiple commands sequentially

Logs & Diagnostics

Tool	USB	WiFi	Description
syslog	Y	Y	Syslog entries with filter
crash_logs	Y	Y	Pull crash reports
device_console	Y	Y	Console output snapshot
diagnostics	Y	-	Hardware diagnostics
ioreg	Y	Y	IORegistry queries
list_processes	Y	Y	Running processes with filter
list_profiles	Y	-	Provisioning profiles

Jailbreak Package Management (WiFi/SSH)

Tool	Description
jb_installed_packages	List dpkg packages with filter
jb_install_package	Install package via apt
jb_remove_package	Remove package
jb_add_repo	Add Sileo/Zebra source
jb_list_repos	List configured repos
jb_tweak_list	List MobileSubstrate tweaks
uicache	Rebuild icon cache
respring	Reload SpringBoard

Jailbreak Filesystem (WiFi/SSH)

Tool	Description
jb_filesystem_browse	Recursive directory listing with full root access
jb_read_file	Read any file on device
jb_write_file	Write to any file
jb_find_files	Find files by pattern across entire filesystem
jb_plist_read	Read plist files in human-readable format

Frida Integration (WiFi/SSH)

Tool	Description
frida_ps	List processes via Frida
frida_list_apps	Detailed app listing via Frida
frida_spawn	Spawn app with optional JavaScript injection
frida_trace	Trace function calls in apps

Security / Pentest (WiFi/SSH)

Tool	Description
ssl_killswitch_status	Check SSL pinning bypass tweaks
app_binary_info	Binary security flags (PIE, ARC, encryption)
app_data_dir	Find and browse app data directories
jb_keychain_dump	Dump keychain entries
tcpdump_capture	Network traffic capture (pcap)

Pairing & Network

Tool	USB	WiFi	Description
pair_device	Y	-	Pair device (triggers trust dialog)
validate_pair	Y	-	Check pairing status
proxy	Y	-	TCP port forwarding

---

Full Filesystem Coverage

When listing apps, the server scans all known iOS and jailbreak directories:

Directory	What's There
/var/containers/Bundle/Application/	App Store and sideloaded apps
/Applications/	iOS system apps
/var/jb/Applications/	Rootless jailbreak apps (Dopamine, palera1n rootless)
/cores/binpack/Applications/	Jailbreak loader apps (palera1n, checkra1n)
/private/var/containers/Bundle/tweaksupport/Applications/	Legacy tweak support apps

This ensures tools like palera1n Loader, Sileo, Zebra, NewTerm, and any other jailbreak app are always found — no matter where they're installed.

---

Environment Variables

Variable	Default	Description
IPHONE_UDID	(empty = auto-detect)	Target device UDID. Leave empty for single-device setups
IPHONE_HOST	(empty)	Device WiFi IP address for SSH connection
IPHONE_SSH_PORT	22	SSH port on device
IPHONE_SSH_PASS	alpine	SSH password (change the default!)
IPHONE_SSH_USER	root	SSH user
IPHONE_MODE	auto	Connection mode: usb, wifi, or auto

---

Architecture

                    ┌─────────────┐
                    │ Claude Code │
                    └──────┬──────┘
                           │ MCP (stdio)
                    ┌──────┴──────┐
                    │  server.py  │
                    └──┬───────┬──┘
              USB      │       │     WiFi/SSH
         ┌─────────────┘       └──────────────┐
         │                                     │
   ┌─────┴──────┐                      ┌───────┴──────┐
   │libimobile-  │                      │   sshpass +  │
   │device +     │                      │   ssh/scp    │
   │pymobile-    │                      │              │
   │device3      │                      │  (port 22)   │
   └─────┬──────┘                      └───────┬──────┘
         │ USB cable                       │ WiFi network
         │                                     │
   ┌─────┴─────────────────────────────────────┴──┐
   │              iPhone (Jailbroken)              │
   │  ┌─────────┐ ┌───────┐ ┌──────────────────┐  │
   │  │ OpenSSH │ │ Frida │ │ Procursus/Rootless│  │
   │  └─────────┘ └───────┘ └──────────────────┘  │
   └──────────────────────────────────────────────┘

---

Usage Examples

> Take a screenshot of my iPhone
> List all installed apps
> What jailbreak packages are installed?
> What's running on the device? Filter for "Safari"
> Execute: cat /etc/passwd
> Trace all NSURLSession calls in com.example.app
> Show me the data directory for com.example.app
> Capture 10 seconds of network traffic
> Install the package "com.example.tweak"
> Respring the device
> Find all .sqlite files on the device
> Read /var/mobile/Library/Preferences/com.apple.springboard.plist
> Dump the keychain
> Check SSL pinning bypass status

---

Troubleshooting

USB not detecting device

sudo systemctl restart usbmuxd   # Linux
idevice_id -l                     # Should show UDID

WiFi/SSH connection refused

• Make sure OpenSSH is installed on the iPhone: apt install openssh-server
• Verify the iPhone is on the same WiFi network as your computer
• Check the IP: Settings > Wi-Fi > tap network > IP Address
• Test manually: ssh root@YOUR_IP (default password: alpine)

Frida not working

• Install Frida server on iPhone: apt install re.frida.server
• Make sure Frida is running: ssh root@YOUR_IP "frida-server -D"
• Install matching Frida version on host: pip install frida-tools

Apps not showing in list

The server scans all known directories. If an app is still missing, use:

> Find files named "Info.plist" starting from /

---

Security Notes

• USB mode: All communication over USB — no network exposure
• WiFi mode: SSH encrypted tunnel over local network
• Credentials: SSH password stored in environment variable, not in code
• The shell tool gives full root access — use responsibly
• Designed for security research and authorized testing only
• Change the default SSH password (alpine) immediately after setup

License

MIT