@purplesquirrel/iphone-mcp

MCP server for controlling your iPhone through macOS iPhone Mirroring. Gives AI agents full access to any iPhone app via tap, swipe, type, screenshot, and OCR.

Requirements

• macOS Sequoia 15+ with iPhone Mirroring
• iPhone paired and mirroring active
• cliclick (brew install cliclick)

Tools

| Tool | Description | |------|-------------| | iphone_status | Check if iPhone Mirroring is running | | iphone_launch | Activate iPhone Mirroring | | iphone_screenshot | Capture the iPhone screen | | iphone_ocr | Screenshot + OCR to extract text | | iphone_tap | Tap at coordinates or on text (via OCR) | | iphone_swipe | Swipe up/down/left/right | | iphone_type | Type text on the iPhone keyboard | | iphone_home | Go to home screen | | iphone_open_app | Open any app by name | | iphone_back | iOS back gesture | | iphone_wait_for_text | Wait until text appears on screen | | iphone_sequence | Run multiple actions in order |

Setup

{
  "mcpServers": {
    "iphone": {
      "command": "node",
      "args": ["path/to/iphone-mcp/dist/index.js"]
    }
  }
}

Examples

Open Instagram and take a screenshot:

iphone_open_app({app_name: "Instagram"})
iphone_screenshot()

Check Phantom wallet balance:

iphone_open_app({app_name: "Phantom"})
iphone_wait_for_text({text: "SOL"})
iphone_ocr()

Multi-step sequence:

iphone_sequence({steps: [
  {action: "home"},
  {action: "swipe", direction: "down", delay_ms: 500},
  {action: "type", text: "Safari"},
  {action: "wait", delay_ms: 800},
  {action: "tap", x: 160, y: 200},
  {action: "ocr"}
]})

How It Works

Uses three native macOS capabilities through the iPhone Mirroring window:

1. AppleScript (System Events) — activate window, send keystrokes
2. cliclick — precise coordinate-based clicks and drag gestures
3. screencapture — window-cropped screenshots + Apple Vision OCR

License

MIT