Getting Started
iphone-use
Let AI agents use your real iPhone. With iphone-use installed on your Mac, Claude Code, Codex or any MCP client reads the phone's screen as text, taps, types and swipes in any app, including the ones with no API: Health, banking, chat apps, or the app you are testing. You can watch it live and take the phone back at any time.
$ curl -fsSL https://raw.githubusercontent.com/leeguooooo/iphone-use/main/install.sh | shConnect your agent in three steps
- Get the phone ready: a Mac with macOS 15 or later and Xcode signed in to an Apple ID (a free one works), an iPhone with iOS 15 or later and Developer Mode on (Settings β Privacy & Security β Developer Mode), and a USB cable for the first setup. Plug the iPhone in and unlock it.
-
Run the installer above. It sets the phone up, shows an agent opening Settings and reading it,
registers the MCP server with Claude Code and Codex (and with Cursor and Claude Desktop when they are
installed), and opens the control page in your browser with a one-time sign-in. If anything is missing, it
says what and how to fix it.
bash
$ iphone-use doctor # what is missing, and how to fix it $ iphone-use try # a harmless check: open Settings, read the screen, go Home - Ask your agent. Start a new chat in Claude Code or Codex and say what you want done on the phone. You do not need to learn any commands; the bundled skill teaches the agent the loop. Other clients: MCP, HTTP API and skill.
Full requirements, plugins, upgrades and a second phone: Install.
Ask your agent
Requests like these work in any app on the phone. The agent finds an app by its name, types long text in one step and reads a list across pages.
Open Health and tell me how many steps I walked each day this week.
The screen comes back as text (an accessibility tree), not pixels.
Find the newest message from Mom in WeChat and read it to me.
Taps, typing (CJK included) and swipes go through a small XCTest runner on the phone.
Collect every transaction on this bank statement page, all the way to the end.
It reads a list across pages and says whether it reached the end. Screens hidden from capture are driven by their elements.
Write this 2,000-word draft into a new note in Notes.
Up to 20,000 characters in one typing step.
Run my app's login test on the real phone and tell me which step fails.
Logs, crash reports, screen recording, installing a build and a simulated location are in the same tools.
Save what you just did as a flow so it runs in one call next time.
A saved flow replays with no model and no tokens.
Without the terminal
Paste one prompt into Codex or Claude Code. It runs the installer and stops for the steps only you can do, such as tapping Trust on the iPhone. It never asks for a password or a code.
A live H.264 screen: click to tap, drag to swipe, type with your own input method. The Flow panel records what you do.
The native iOS app pairs by scanning a QR code on the Mac's page, with no address or password to type.
The phone's screen shows in the agent host's side panel where MCP Apps is supported, in a browser, or in the iOS app.
Why a real iPhone
Health, banking and payment apps (even the ones that black out screen capture), chat apps, and your own app under test, with the sign-ins already on the phone.
Set the phone up once with a cable; then drive it over Wi-Fi through an encrypted tunnel. iOS 15 and later, without updating the phone.
Every action reports whether it was applied, not sent, or unknown, and whether a retry is safe. Taps on covered elements are refused.
It never touches the Mac's screen, cursor or focus. Agents and people share the phone; one of them holds it at a time.
Under the hood
One daemon per phone runs on your Mac. It reads the screen as an accessibility tree, sends taps and typing through its own XCTest runner on the iPhone, and checks that the screen has settled before it answers.
The daemon, the XCTest runner, USB and the Wi-Fi tunnel, idle release and handing the phone back.
Config for Claude Code, Codex, Cursor, VS Code, Claude Desktop, Gemini CLI, opencode and Windsurf.
Reviewed per-app scripts, the official registry, test suites and scheduled runs.
mobile-mcp, agent-device, Appium and other iPhone MCP servers, from their own READMEs.
Quick answers
Does it need a jailbreak?
No. It needs Developer Mode on the iPhone and a signed XCTest runner, which the installer builds with your Xcode team.
Which agents can use it?
Claude Code, Codex, Cursor, Claude Desktop and any other MCP client, through the bundled MCP server. Scripts and other agents can call the HTTP API under /agent/*.
Does it need a Mac?
Yes. The daemon runs on a Mac with macOS 15 or later and Xcode. Other devices can reach its browser page and APIs, but the phone itself is hosted by the Mac.
Is it free and open source?
It costs nothing to download and use. It is source-available under the PolyForm Shield 1.0.0 license, not an OSI-approved open-source license: non-competing use, modification and distribution are permitted, while using it to provide a competing product or service is not.
More in the FAQ.
The *-use family
Small tools that give an AI agent hands on one real thing you already use.
Lets agents use your real, signed-in Chrome.
The author's blog post: install, MCP setup, flows and how it compares.
iphone-use in one minute; every phone shot is a real recording.
Paid setup and sponsorship
Need help setting up a real iPhone, connecting your agent or creating an iOS app test flow? Email the maintainer with your environment, the workflow and expected result, and where you are stuck; scope, acceptance criteria and a quote are agreed before work starts. Bug reports and feature requests stay welcome on GitHub issues. Please keep credentials and private account data out of inquiries.
PolyForm Shield 1.0.0 (source-available) Β· GitHub Β· made by Guo Li (ιη«) Β· Privacy