iphone-use MCP
Lets Claude Code and Codex drive a real iPhone: read the screen, tap, type and scroll in any app
- 399 ★ on the repository
- Last commit
Broad access
Why this level
- The agent taps and types in any phone app, including banking apps and messengers
- Through the screen the agent reads personal data such as messages and Health records
- The source is under PolyForm Shield: commercial use is limited by the author's terms
Install
- Works in
Manual install
curl -fsSL https://raw.githubusercontent.com/leeguooooo/iphone-use/main/install.sh | shRun it on a Mac with the iPhone plugged in and unlocked. The script sets up the phone and registers the MCP server.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The agent taps and types in any phone app, including banking apps and messengers
- Through the screen the agent reads personal data such as messages and Health records
- The source is under PolyForm Shield: commercial use is limited by the author's terms
This is third-party code. Review the repository files before installing.
What it does
iphone-use drives a physical iPhone from a Mac. A daemon runs on the Mac, and a small XCTest runner is installed on the phone. The daemon reads the screen as an accessibility tree, meaning text with no screenshot needed, and sends taps, typing and gestures to the phone. Before it answers, it waits for the screen to settle. The agent gets tools with the phone_ prefix. They open an app by name, read the screen elements and run a batch of steps in one call. Up to 20 thousand characters can be typed at once. Every action returns a status (applied, not sent or unknown) and says whether a retry is safe. A tap on a covered element is refused. A task you repeat can be recorded as a flow: a script for one app that later runs in a single call with no model and no tokens. For people there is a web page that streams the phone screen in real time and an app for control from a second iPhone. Control works over USB and over Wi-Fi. For app developers the same tools pull logs and crash reports and record the screen to video. They also install .ipa builds and fake the location.
Who it is for. For iOS app developers and testers, and for anyone who wants to automate iPhone apps that have no API with Claude Code, Codex or Cursor.
Good fit when
- You need to run your own app's login flow on a real phone and see which step breaks
- You need data out of an app without an API, such as a week of steps from Health or the transactions on a statement page
- You want test suites for an iOS app with an exit code that CI understands
- You want to watch the agent on the streamed phone screen and take over from a browser at any moment
- You need a test on an older iPhone stuck on iOS 15
Not a fit when
- You have no Mac: the server runs only on macOS
- You need Android: the project drives iPhones only
- The task fits the app's own API: a direct API call is simpler and cheaper than tapping through the screen
Example request
Open Health on my iPhone and tell me how many steps I walked each day this week.MCP
- Transport
- stdio, http
- Authentication
- not required
Environment variables
IPHONE_USE_BLOCKED_APPS- Apps the daemon refuses to open, for example Wallet and Passwords
IPHONE_USE_MAX_ACTIONS- Cap on the number of actions per task
IPHONE_USE_MCP_TOKENsecret- Token for MCP over HTTP on a non-loopback address; the mode will not start without it
Limitations
The license is PolyForm Shield 1.0.0: the code is open to read and modify, but it cannot be used for a competing product or service, even a free one.
The first setup is manual, over a cable and with the phone unlocked. On iOS 15 and 16 the local network link is unencrypted. Banking apps hide the screen from capture, and then the agent sees only a wireframe of the elements.
The agent never types passwords, codes or Face ID: it stops and asks you to finish the sign-in on the phone. A free Apple ID is enough for the runner, while the app for control from a second iPhone without a Mac needs a paid developer account.
How to disable. The `~/.iphone-use/uninstall.sh --dry-run` command shows what would be removed, and running it without `--dry-run` removes the install. Plugins are removed with the usual Claude Code and Codex commands. To hide the writing tools from the agent, set `IPHONE_USE_MCP_TOOLS=readonly` and only the reading tools remain.
FAQ
How do I install iphone-use in Claude Code?
Run the installer script first on the Mac with the iPhone plugged in: it sets up the phone and registers the MCP server with Claude Code and Codex, and with Cursor and Claude Desktop when they are installed. You can also add the plugin with `/plugin marketplace add leeguooooo/iphone-use` and `/plugin install iphone-use@iphone-use`. It adds the skill and the server, but the installer is still required.
What is a flow in iphone-use?
A reviewed script for one app. The agent does the task once, the daemon records the steps as a draft, and later the script runs in a single call with no model, for example with `flow run health/export-all-zh-cn`. Ready-made flows come from the iphone-use-flows registry.
Can I stop the agent from opening certain apps?
Yes. The IPHONE_USE_BLOCKED_APPS variable lists the blocked apps, for example Wallet and Passwords, and IPHONE_USE_MAX_ACTIONS caps the number of actions per task. The daemon enforces these limits whatever the agent's prompt says.
Does iphone-use send data anywhere?
This build sends no usage data. The daemon listens on 127.0.0.1:44321 behind a password, and the runner on the phone accepts only requests signed with a per-launch token. Typed text is not logged, only its length.
What does the first setup of iphone-use need?
A Mac with macOS 15 or later, Xcode signed in to an Apple ID (a free one works), an iPhone with iOS 15 or later and Developer Mode on, and a USB cable. Unlock the phone before installing. If anything is missing, the `iphone-use doctor` command names it and says how to fix it.
Discussion
No questions or reviews yet.
Related
MCP serversAn MCP server to drive iOS and Android: simulators, emulators and real devices via accessibility trees and screenshots
The npx serve-sim command streams an iOS Simulator to the browser and lets an agent tap, swipe, type and replace the camera feed
An MCP server for the iOS Simulator: taps, swipes, text input, accessibility tree, screenshots, video and app control
A DeepSeek Harness plugin: iOS Simulator and a USB iPhone inside the chat, with 22 tools to drive them
Skills and a CLI that let Claude Code, Codex and OpenCode operate an Android phone: open apps, tap, type and test workflows
An MCP server that drives a real iPhone through macOS iPhone Mirroring: the agent sees the screen, taps, swipes and types
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| iphone-use (this entry) | no | not required | 399 | |
| Mobile MCP | no | not required | 10,126 | drives iOS and Android through one MCP server, while iphone-use covers iPhone only and adds recorded flows that replay without a model |
| agent-device | no | 5,183 | also gives the agent a mobile device, while iphone-use reads the screen faster in the author's measurements |
README in short
The documentation includes speed measurements on an iPhone 13 over USB: reading the screen takes 0.08–0.135 s, about 0.7 s for agent-device. It also covers remote control from a browser, an HTTP API for scripts and scheduled test suites.