
Control a real USB-connected iPhone from Linux (no Mac, no paid developer account) and expose it to
Control a real USB-connected iPhone from Linux (no Mac, no paid developer account) and expose it to AI agents as MCP tools
·
Let an AI agent operate a real iPhone or iPad plugged into a Linux machine or a Mac, reliably and fast — one Rust binary, no Xcode, no paid developer account, no jailbreak, and from iOS 27 no Apple ID either.
🚀 Quick Start · 📖 Docs · 📦 Releases · 🐛 Issues · 🌐 简体中文
Asking Claude Code to “open Clock, switch to the stopwatch and start it”. Left: Claude Code’s tool calls (first part only). Right: the phone afterwards.
AI agents can drive browsers and desktops, but a real iPhone is harder: Apple's automation tools need a Mac and Xcode, and the open-source alternatives come as separate pieces that each need their own setup, signing and babysitting.
iphone-control does it all in one Rust binary on Linux or macOS, built on idevice, Impactor and WebDriverAgent. It succeeds iphone-control-toolkit and keeps its MCP tools compatible.
It has three layers, and device control is the core:
| Layer | What it does | Needs the control page? |
|---|---|---|
| Device control (core) | A long-running daemon owns the phone and serves the MCP tools; recovers from unplugging and reboots; pausing, taking over and confirming AI tasks | No |
| Access | AI clients on this machine connect over stdio; other machines over HTTP MCP (/mcp) or mcp --url | Locally no; remotely the viewer service must run |
| Control page (optional) | Watch the live screen in a browser, act on it, hand out AI tasks | It is the control page |
Device control has two routes, picked by iOS version:
[!TIP] Use a device on iOS 27 or later if you can, or update the phone to iOS 27: no Apple ID sign-in, no signing, no "Enable UI Automation" passcode after a reboot, and none of the expiring profiles, revoked certificates or stuck WebDriverAgent that come with it.
Device control (core)
iphone_batch runs up to 20 steps in one calldoctor checks every layer from USB up and tells you how to fix each failureAccess
task run runs any agent platform in a task whose every step you can follow/mcp) on its port, over HTTPS with a login token (read-only ones too) when opened to the network; mcp --url and task --url use a phone on another machineControl page (optional)
You need an iPhone or iPad (iOS 27+ recommended, iOS 17+ supported) connected by a data cable, and an Apple Silicon Mac or a Linux machine. On iOS 26 and earlier you also need a free Apple ID (use a dedicated one) to sign WebDriverAgent.
macOS or Linux, one command (upstream example; for a fork, use the installer asset from its own signed release)
curl -fsSLo iphone-control-install.sh https://github.com/Derrors/iphone-control/releases/latest/download/install.sh && sh iphone-control-install.shIt downloads the release for your machine, verifies the Ed25519 release manifest and archive SHA-256 (Python 3 and OpenSSL 3 required), installs iphone-control into ~/.local/bin and runs the daemon as a per-user service that starts at login (launchd on macOS, systemd on Linux). Run it as your regular user. Use iphone-control update to upgrade this managed service. Running sh iphone-control-install.sh --uninstall removes it and keeps your data.
Upstream v0.2.0 predates the signed installer. To install that release or migrate an existing script installation, follow the v0.2.0 instructions.
Or with a package manager
# macOS or Linux (Homebrew)
brew install derrors/tap/iphone-control && brew services start iphone-control
# Debian 12+ / Ubuntu 22.04+: the .deb from Releases (amd64 or arm64), pulls in usbmuxd
sudo apt install ./iphone-control_<version>_amd64.deb && systemctl --user enable --now iphone-controlOn Linux the system usbmuxd is needed (sudo apt install usbmuxd; the .deb brings it). On an Intel Mac, build from source.
Then, on every system
Connect the phone with the cable and run:
iphone-controlThe first time, it walks you through setup in the terminal, one step at a time: language, proxy, the background service, pairing, Developer Mode (and on iOS 26 and earlier, Apple ID and signing and installing WebDriverAgent), the optional auto-unlock and notifications, and registering with Claude Code and Codex. Do what it asks on the phone. Steps already done are skipped; afterwards, iphone-control just shows the status.
Then open a new Claude Code or Codex session and ask, for example, “Open Clock, switch to the stopwatch and start it.” That is device control, complete; the control page is optional. To watch the phone in a browser, run iphone-control viewer for the control page in the browser (http://127.0.0.1:8200; log in with the link iphone-control viewer token prints), where you can act on the live screen and hand tasks to a local Claude Code or Codex; it works from the local network and other machines too, see Viewer and Remote Use.
More: step-by-step guide · build from source · macOS guide · other MCP clients.
| Tool | Description |
|---|---|
iphone_status | Connection, lock state, foreground app, screen size |
iphone_screenshot | Screenshot scaled to points; pass x/y/width/height to zoom into a region |
iphone_list_elements | Elements with text and their center coordinates; filter by text or type |
iphone_tap / iphone_tap_element | Tap by coordinates or by element text |
iphone_swipe / iphone_long_press | Swipe (returns once the list stops), long-press |
iphone_type_text | Type into the focused field; reads it back and fixes dropped characters |
iphone_press_button | home, volume_up, volume_down, lock |
iphone_list_apps / iphone_launch_app / iphone_terminate_app | Manage apps by name or bundle ID |
iphone_open_url | Open a URL or URL scheme |
iphone_wait_for | Wait until some text appears instead of polling with screenshots |
iphone_batch | Run up to 20 steps in one call, stopping at the first error |
iphone_list_devices | Every iPhone/iPad on USB; marks the one being controlled |
iphone_select_device | Switch to another device, or back to automatic choice |
IPHONE_CONTROL_DEV_TOOLS=1 adds six opt-in developer tools: logs, crash reports, installing and removing apps, and two for Web Inspector (list web pages, run JavaScript in them). They are off by default; read the security notes before turning them on.
Action tools accept then: "elements" | "screenshot" to return the screen after the action. Screenshot pixels are tap coordinates, so the agent can tap what it sees. Games, maps and video players draw their own UI and have no element tree — use screenshots and coordinates there. Full parameters: docs/tools.md.
Tool texts, results, CLI output and logs are in Simplified Chinese by default; set IPHONE_CONTROL_LANG=en for English (configuration).
| Command | What it does |
|---|---|
| (none) | The first time, the setup guide; after that, the status (and starts the service if it isn't running) |
setup [--reconfigure] | Run the setup guide again; --reconfigure redoes one part (language, proxy, service, Apple ID, phone, auto-unlock, notifications, MCP registration) |
service install|uninstall|start|stop|restart|status | The background service (launchd on macOS, systemd user unit on Linux) |
daemon | The long-running daemon; the service runs it, or start it by hand |
mcp [--url <viewer>] | The MCP server; your AI client starts it. With --url it bridges to another machine's viewer |
status | Daemon state, time left on the signing profile, recent log |
doctor | Layer-by-layer health check with a fix for each failure |
login | Sign in to the Apple ID again when the session expires (WebDriverAgent devices only) |
sign | Sign and install WebDriverAgent now (likewise) |
resign [--force] | Re-sign WebDriverAgent if it expires soon (or now) (likewise) |
passcode set|clear | Turn auto-unlock on or off for a device (passcodes are kept per device) |
unlock-reset | Turn auto-unlock back on after it was disabled |
devices / select <UDID|name|auto> | List connected devices / switch which one is controlled |
notify-test [event] | Send test notifications |
mcp-config | Print the command that registers the MCP server |
wda-bridge [--port] | Expose WebDriverAgent on 127.0.0.1 for other tools; stop it when done (WebDriverAgent devices only) |
viewer [--port] [--lan] | Control page on 127.0.0.1:8200, behind a login (viewer token shows the token and a link; read-only tokens too): live screen you can tap, swipe and type on, device panel, and AI tasks run by a local Claude Code or Codex. --lan opens it to the local network (HTTPS), and MCP over HTTP is on the same port (/mcp) |
task run [--url <viewer>] -- <command> | AI tasks for other agent platforms; with --url the phone is on another machine. task list, pause, approve… follow and control tasks |
viewer token [add <name> [--read-only]|list|show <name>|remove <name>] | The viewer's login tokens: show the owner's, or add named and read-only ones |
service viewer install|uninstall|start|stop|restart | Run the viewer as a background service of its own |
update check|apply|policy | Check for, install, or set the policy for updates |
completions <shell> | Bash, Zsh or Fish completion script |
All commands and options: CLI reference.
Run iphone-control update to check for a stable release. When an upgrade is available, it uses the signed update for a managed service, Homebrew for a tap installation, or apt for a Debian package. It reports when you're up to date. Source installations follow the source upgrade instructions.
To check versions, open About & updates in Viewer or run iphone-control update check --json. Managed services can opt in to signed patches while idle with iphone-control update policy auto-patch. Use iphone-control update policy notify to return to checks only. Read the upgrade notes before upgrading.
Uninstall with sh iphone-control-install.sh --uninstall, brew uninstall iphone-control or sudo apt remove iphone-control; your data stays. Settings live in ~/.config/iphone-control/env: the guide writes it, and after editing it by hand run iphone-control service restart — see configuration. All state lives in ~/.local/share/iphone-control: the Apple ID session and signing key, and the passcode if auto-unlock is on. Back it up; never commit or share it.
| Guide | What is it · Limitations · Getting started · AI clients · Tools |
| Usage | Configuration · CLI · Several devices · Notifications · Auto-unlock |
| Deployment | Install · Build from source · macOS · Data and backups |
| Problems | FAQ · Troubleshooting · Issues |
| Security | SECURITY.md: what is stored, who can reach it, reporting vulnerabilities |
| Development | Contributing · Architecture · Decisions · Changelog |
| Licensing | THIRD_PARTY.md: vendored components, versions and licenses |
The architecture and design documents are in Chinese for now.
[!WARNING] This tool can fully control your phone. An agent may tap payment, delete or send buttons — keep tool-call confirmation on in your MCP client. Not affiliated with Apple; use it only with devices and accounts you own. Read SECURITY.md before enabling auto-unlock.
Issues and pull requests are welcome — see the contributing guide.
MIT. Third-party components: THIRD_PARTY.md.
This repo does not document an install step we could read. Check the README on GitHub.
Paste this prompt into your agent. It reads this page and does the setup for you.
Read https://aiagentslisting.com/mcp/macos-or-linux-homebrew to learn what the "macOS or Linux (Homebrew)" MCP server does and how to install it. Add it to my coding agent's MCP configuration as documented on that page, then confirm the server connects and list the tools it exposes.Agents can also browse this directory over MCP at https://aiagentslisting.com/api/mcp
This server doesn't publish a machine-readable tool manifest, and it doesn't expose a public endpoint we could ask. Connect the server locally to see what it exposes.
We could not run this server: it ships no npx package for our sandbox and no public endpoint. The four checks that need a live server are left out, and the grade tops out at B until one exists.
Maintain this server? Claiming proves you own the listing and earns the last 4 points.
Claim this listingPaste this line near the top of your repository's README. The badge always renders the current score.
[](https://aiagentslisting.com/mcp/macos-or-linux-homebrew)Nothing comparable is listed yet.
v0.2.7Release notesv0.2.6Release notesv0.2.5Release notesv0.2.4Release notesv0.2.3Release notesv0.2.2Release notesv0.2.1Release notesv0.2.0Release notesv0.1.5Release notesv0.1.4Release notesv0.1.3Release notesv0.1.2Release notesv0.1.1Release notesv0.1.0Release notesConnect to the AI Agents Listing MCP server at https://aiagentslisting.com/api/mcp using the HTTP transport and complete the sign-in when it asks. Then call the submit_review tool for the listing "macos-or-linux-homebrew" with a rating from 1 to 5 and a short note on what worked and what did not.No reviews yet
Be the first to share your experience with this tool.
One email a week. New agents, MCP servers and skills, and what is actually getting traction.