English · 中文

phonectl-mcp

Let AI agents see and drive a real iPhone from your Mac, over USB or Wi-Fi.

Install · Tools · Troubleshooting · Security

An MCP server for screenshots, on-screen text, taps, swipes, typing, buttons, apps and the clipboard on an iPhone connected to your Mac. Nothing to install on the phone, no jailbreak.

An AI agent makes a rednote post: text card, template, stickers, filter, caption. It stops before Post. Sped up.	A script applies to a job in a recruiting app: read_text finds the buttons, tap presses them. 2× speed.

Requirements

• A Mac with uv
• An iPhone on iOS 27 or later, with Developer Mode on
• A USB data cable (not a charge-only one) for the first setup. After that, Wi-Fi works too

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

Install

Let your agent install it

Paste this to your coding agent (Claude Code, Codex, Cursor…):

Install phonectl-mcp by following https://github.com/jiefeng-ai/phonectl-mcp#install-by-hand, then add it to your MCP config and take a screenshot of my phone to check it works. When I need to do something on the phone, tell me step by step and wait for me.

Install by hand

uv tool install phonectl-mcp
phonectl install-service   # runs the server at login on http://127.0.0.1:47321/mcp
phonectl doctor            # checks cable, trust, Developer Mode, disk image and server

install-service also creates an access token in ~/.config/phonectl/token. Then connect your 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)"

Cursor (~/.cursor/mcp.json) and other clients with streamable HTTP

{
  "mcpServers": {
    "phone": {
      "url": "http://127.0.0.1:47321/mcp",
      "headers": { "Authorization": "Bearer <contents of ~/.config/phonectl/token>" }
    }
  }
}

To check, ask your agent to take a screenshot of the phone.

After one setup over the cable, it also works over Wi-Fi while the phone and the Mac share a network.

All agents and scripts share this one server, since the phone takes a single control connection; let one agent drive at a time.

Tools

Coordinates are iOS points, the same as the pixels of the returned screenshot.

Tools that act on the phone return a screenshot taken afterwards (screenshot=False skips it). Taps are not confirmed, so check that screenshot.

Troubleshooting

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

Security

• The server listens only on 127.0.0.1 and rejects requests without the token.
• An agent can do anything your finger can: send messages, pay, delete. Keep its instructions narrow and watch the screen. Use at your own risk; automating third-party apps may break their terms.

Settings

Other commands: phonectl restart (e.g. after uv tool upgrade phonectl-mcp). To remove: phonectl uninstall-service, uv tool uninstall phonectl-mcp, and delete ~/.config/phonectl.

Development

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

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

License

MIT