Let AI agents control your iPhone: MCP server, CLI and HTTP API

Updated October 9, 2026

Mirror my iPhone gives AI agents a real iPhone. Claude, Cursor, Codex or your own script can see the screen, read its buttons and fields, and tap, swipe, type and open apps on an iPhone connected to your Mac by USB. They call tools that act on the phone directly, with no computer use involved.

Why a direct API instead of computer use

The usual way to let an AI use a phone from a Mac is computer use: the agent screenshots your whole desktop, finds the mirroring window, and moves your mouse to click inside it. Apple's iPhone Mirroring offers nothing else, because it has no API. Mirror my iPhone skips all of that:

• Exact targets. describe_ui lists the buttons, text fields and cells on screen from iOS accessibility, each with the point to tap. The agent doesn't have to guess positions from pixels.
• Results, not animations. Each gesture returns once the iPhone has performed it, followed by a screenshot taken after the screen settles.
• Small screenshots. One pixel per iPhone point (393 × 852 on an iPhone 15) instead of your whole desktop.
• Your Mac stays yours. The agent never touches your mouse or keyboard. The app has to be open, but its window can stay in the background while you work.
• One API, three ways in. An MCP server for agents, a CLI for shell scripts, and HTTP for everything else.

Quick start

1. Install Mirror my iPhone, open it and let the Doctor set up touch control (Xcode, a free Apple ID and Developer Mode on the iPhone).
2. Add the MCP server to your agent, using one of the configurations below.
3. Ask something like "Open Settings on my iPhone and turn on Dark Mode." You see every agent touch as a blue dot on the mirrored screen.

Claude Code

$ claude mcp add --scope user mirror-my-iphone -- "/Applications/Mirror my iPhone.app/Contents/Resources/bin/mirror-my-iphone" mcp

Claude Desktop, Cursor and Gemini CLI

Add this to ~/Library/Application Support/Claude/claude_desktop_config.json (Claude Desktop), ~/.cursor/mcp.json (Cursor) or ~/.gemini/settings.json (Gemini CLI):

{
  "mcpServers": {
    "mirror-my-iphone": {
      "command": "/Applications/Mirror my iPhone.app/Contents/Resources/bin/mirror-my-iphone",
      "args": ["mcp"]
    }
  }
}

VS Code

In .vscode/mcp.json:

{
  "servers": {
    "mirror-my-iphone": {
      "type": "stdio",
      "command": "/Applications/Mirror my iPhone.app/Contents/Resources/bin/mirror-my-iphone",
      "args": ["mcp"]
    }
  }
}

Codex CLI

In ~/.codex/config.toml:

[mcp_servers.mirror-my-iphone]
command = "/Applications/Mirror my iPhone.app/Contents/Resources/bin/mirror-my-iphone"
args = ["mcp"]

Any other MCP client that runs local (stdio) servers works the same way.

Tools

Coordinates are iPhone points, which are also the pixels of a default screenshot, with (0, 0) at the top left.

Gesture tools answer with a screenshot of the result, so the agent sees each step without asking.

What the agent sees

Example output of describe_ui (or mirror-my-iphone ui) in Settings:

In front: Settings (com.apple.Preferences). Screen 393 × 852 points. Keyboard hidden.
SearchField "Search" at (196.5, 160)
Cell "Wi-Fi" value "Home" at (196.5, 398)
Cell "Bluetooth" value "On" at (196.5, 442)
Cell "Display & Brightness" at (196.5, 640)
...

HTTP API for scripts and other agents

While it runs, the app serves the API on 127.0.0.1:8101 (or a free port). It writes the URL and a token to ~/Library/Application Support/Mirror my iPhone/api.json, which only your user account can read. Every request needs the token.

$ API="$HOME/Library/Application Support/Mirror my iPhone/api.json"
$ URL=$(plutil -extract url raw -o - "$API") TOKEN=$(plutil -extract token raw -o - "$API")
$ curl -H "Authorization: Bearer $TOKEN" "$URL/v1/screenshot" -o screen.png
$ curl -H "Authorization: Bearer $TOKEN" -d '{"x": 196, "y": 400}' "$URL/v1/tap"

The same from Python, with only the standard library:

import json, pathlib, urllib.request

api = json.loads((pathlib.Path.home() / "Library/Application Support/Mirror my iPhone/api.json").read_text())

def call(path, body=None):
    data = json.dumps(body).encode() if body is not None else None
    request = urllib.request.Request(api["url"] + path, data=data,
                                     headers={"Authorization": f"Bearer {api['token']}"})
    return urllib.request.urlopen(request).read()

call("/v1/open_app", {"bundle_id": "com.apple.Preferences"})
print(json.loads(call("/v1/ui"))["elements"][:5])
pathlib.Path("screen.png").write_bytes(call("/v1/screenshot"))

GET /v1 lists every endpoint. The README has the full parameter reference.

What people use it for

• Testing iOS apps on a real device. Build with Xcode, then let Claude Code open your app, tap through a flow and check the screenshots and on-screen elements.
• Reproducing bugs step by step, with a screenshot after every action.
• Accessibility checks. describe_ui shows which buttons and fields have labels and which don't.
• Phone chores you'd rather describe than click through, with you watching every touch.

Safety and privacy

• The API listens only on 127.0.0.1 and refuses requests from web pages, so websites can't reach your phone through your browser.
• Every request needs the token from a file only your user account can read.
• The MCP server tells the agent this is your own phone and to ask before anything hard to undo, like sending messages, buying, deleting data or changing security settings.
• You see each agent touch as a blue dot on the mirrored screen, and nothing leaves your Mac except what your agent sends to its model.

Limitations

• The iPhone's screen has to be on. Screenshots go stale while it sleeps, and the agent is told so. Raise Auto-Lock in Settings › Display & Brightness to keep it awake.
• Touch control needs Xcode and Developer Mode on the iPhone. With a free Apple ID, WebDriverAgent's signing profile lasts 7 days, and the app signs it again automatically.
• Agent gestures and your mouse share one queue, so they run one after another.

FAQ