home / mcp / iphone mirroir mcp server

iphone mirroir MCP Server

Controls a real iPhone via macOS iPhone Mirroring, enabling screenshots, video, taps, swipes, typing, and app navigation from MCP clients.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "jfarcand-iphone-mirroir-mcp": {
      "command": "npx",
      "args": [
        "iphone-mirroir-mcp"
      ]
    }
  }
}

You can control a real iPhone from your Mac using the MCP server that interfaces with macOS iPhone Mirroring. You can capture screenshots, record video, tap, swipe, type, and navigate apps visible on the mirrored screen from any MCP client.

How to use

You will run an MCP client that communicates with the iphone-mirrroir-mcp server to control your iPhone. Practical uses include taking screenshots of apps you test, recording high-quality videos of user flows, tapping controls, swiping to scroll, typing text into fields, and launching apps or URLs. Input flows go through Karabiner DriverKit virtual HID devices so your actions mirror real touches and keyboard behavior on the device.

How to install

Prerequisites: you need macOS 15+ with iPhone Mirroring, an iPhone connected to the Mac via iPhone Mirroring, and Karabiner-Elements installed and activated.

Additional setup steps

Install options are provided to suit your preference. The following install methods are described with concrete commands you can copy and run.

Notes on usage and workflow

Typing and key presses flow through the Karabiner virtual HID keyboard. iPhone Mirroring is activated if needed to bring the correct window to the front, and the MCP server keeps the mirroring session active for consistent input without repeatedly switching between apps.

Security and privacy considerations

This setup grants an automation agent full control of your iPhone screen. It can tap, type, and navigate, including sensitive apps. The helper daemon listens only on a local Unix socket, and the driver runs with root privileges for HID access. Use this tool only on devices you trust.

Troubleshooting

If you encounter issues, verify the following: Karabiner-Elements is running and its DriverKit extension is enabled; the helper daemon is active; accessibility permissions are granted for the terminal or client you use; and iPhone Mirroring is active when sending input.

Examples

Examples illustrate typical interaction patterns you can perform through the MCP client, such as launching apps, navigating screens, and performing input actions. Use these as templates to build real workflows for your testing and automation tasks.

Architecture overview

The MCP client communicates with iphone-mirroir-mcp, which coordinates mirroring discovery, screen capture, and input simulation. A helper daemon bridges user input to Karabiner DriverKit, while Karabiner’s HID devices route touch and keyboard events through the macOS HID system into iPhone Mirroring.

Updating and Uninstalling

To update, use your preferred installation method’s update steps (Homebrew or source). To uninstall, stop the service and remove the package according to the method you used to install.

Available tools

screenshot

Capture the iPhone screen as a PNG image in base64 encoding.

start_recording

Begin a video recording of the mirrored screen, saving to a specified output path.

stop_recording

Stop recording and return the path to the produced .mov file.

tap

Tap at specific coordinates relative to the mirroring window.

double_tap

Perform two rapid taps at a given coordinate.

long_press

Hold a tap at a position for a duration to trigger context menus or drag initiation.

swipe

Swipe between two points with an optional duration to simulate scrolling or gestures.

drag

Perform a slow, sustained drag between two points to move icons or adjust sliders.

type_text

Type text into the focused field via Karabiner virtual HID keyboard with layout support.

press_key

Send special keys such as Return, Escape, Tab, arrows with optional modifiers.

shake

Trigger the shake gesture to undo or access developer menus.

launch_app

Open an app by name using Spotlight search.

open_url

Open a URL in Safari on the iPhone.

press_home

Return to the iPhone home screen.

press_app_switcher

Open the App Switcher on the iPhone.

spotlight

Open macOS Spotlight search.

get_orientation

Report device orientation and window dimensions.

status

Provide connection state and window geometry for the current session.