phonectl-mcp

中文

An MCP server that lets AI agents see and drive a real iPhone over a USB cable: screenshots, the text on screen, taps, swipes, typing, hardware buttons, apps and the clipboard. macOS only.

_{A script applying to one job in a recruiting app through phonectl-mcp: read_text finds the buttons, tap presses them. Personal details are pixelated; 2× speed.}

Nothing is installed on the phone and nothing is jailbroken. It uses the developer services iOS already exposes to a trusted Mac (the same ones Xcode uses), and the touch and keyboard input path that iOS 27 opened over USB.

Requirements

• A Mac. The USB tunnel and the on-screen text recognition (Apple Vision) are macOS-only.
• An iPhone on iOS 27 or later. Taps, swipes and typing need iOS 27. Screenshots and app control may also work on iOS 17–26, but this is untested.
• A USB data cable (a charge-only cable won't work).
• On the phone: Developer Mode turned on, and this Mac trusted. phonectl doctor walks you through both.
• uv.

Tested on an iPhone 17 Pro with iOS 27.2 and macOS 27.

Install

uv tool install phonectl-mcp
phonectl install-service
phonectl doctor

• install-service runs the server at login as a launchd job. It listens on http://127.0.0.1:47321/mcp and creates an access token in ~/.config/phonectl/token. It also prints the client setup below.
• doctor checks every link from the cable to the server and says what to do about anything that fails. phonectl doctor --fix mounts the developer disk image if it is missing.

Connect a client

Claude Code:

claude mcp add --scope user --transport http phone http://127.0.0.1:47321/mcp \
  --header "Authorization: Bearer $(cat ~/.config/phonectl/token)"

Any other client that speaks streamable HTTP needs two things: the URL above, and the header Authorization: Bearer <token>.

Why one server for every client

The phone keeps a single control connection to the Mac. If two programs each open their own, they keep knocking each other off. So one resident server owns the phone, and every agent and script connects to that server. Your own scripts can call the same tools with any MCP client library.

This only makes the connection safe to share. The server does not stop two agents from tapping the screen at the same time, so let one drive at a time.

Tools

Coordinates are iOS points, which match the pixels of the screenshot the server returns (402×874 on an iPhone 17 Pro).

The tools that act on the phone (tap, long_press, swipe, type_text, press_key, press_button, launch_app) return a screenshot taken afterwards; pass screenshot=False to skip it. Taps are not confirmed by the phone, so use that screenshot to see whether a tap landed.

Settings

Set these environment variables before running phonectl install-service; it copies them into the service.

Other commands: phonectl restart restarts the server (for example after upgrading with uv tool upgrade phonectl-mcp), and phonectl uninstall-service removes it. Running phonectl-mcp with no arguments speaks stdio for a single client; this is meant for debugging.

Troubleshooting

Run phonectl doctor first. It tells you which link is broken.

Security

• The server listens only on 127.0.0.1 and rejects any request without the token.
• An agent connected to it can do anything you could do with your finger: send messages, buy things, delete data. Give it the narrowest instructions you can, and watch the screen while it works.
• You use it at your own risk. Automating third-party apps may break their terms of service.

Development

git clone https://github.com/jiefeng-ai/phonectl-mcp
cd phonectl-mcp
uv sync
uv run pytest

To run your working copy as the service, run uv run phonectl install-service from the clone.

License

MIT