iphone-control
Control a real USB-connected iPhone from Linux (no Mac, no paid developer account) and expose it to AI agents as MCP tools
Install / Use
claude mcp add Derrors -- npx -y github:Derrors/iphone-controlIf the server publishes to npm under a different name, use that package instead — check the repo README.
MCP Server
Model Context Protocol server
Quality Score
Category
AutomationSupported Platforms
Our assessment of iphone-control
iphone-control scores 85/100 on our quality scale, 1860th of 2,768 Automation skills we index.
Its MCP Server is 18 KB long, well organised into 10 sections with 3 code examples: a thorough specification that gives an agent plenty to work with.
It has 44 GitHub stars, so there is little community track record yet; judge it on its content.
Maintenance, license and trust
- The repository was last updated today, so iphone-control is actively maintained.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 97/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-11-18. Automated pattern scan on 2026-11-18. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
iphone-control compared with similar skills
All 4 of these similar skills score higher than iphone-control; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| iphone-control (this skill)by Derrors | 85 | 44 | today | MCP Server |
| Agent-Reachby Panniantong | 100 | 113.0k | 10d ago | CLAUDE.md |
| hyperframesby heygen-com | 100 | 86.4k | today | CLAUDE.md |
| rufloby ruvnet | 100 | 82.0k | today | CLAUDE.md |
| headroomby headroomlabs-ai | 100 | 80.1k | today | CLAUDE.md |
Frequently asked questions
- How do I install iphone-control?
- Run
claude mcp add Derrors -- npx -y github:Derrors/iphone-control. The install tabs above show the steps for each supported agent. - Which AI agents does iphone-control work with?
- It is written for Claude Code and Claude Desktop, as a MCP Server file. Other agents that read the same format can often use it too.
- Is iphone-control safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 97/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is iphone-control still maintained?
- The repository was last updated today, so iphone-control is actively maintained.
Skill content
View source on GitHubOverview
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:
- iOS 27 and later: native control (default). The screen is read through the system's accessibility service, taps, swipes and buttons go through HID, and apps launch through CoreDevice. Nothing is installed on the phone: no Apple ID, no signing, ready in seconds.
- iOS 17–26: WebDriverAgent. Signed with a free Apple ID, installed on the phone and re-signed before the 7-day profile expires. This route stays maintained.
<p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="website/public/architecture-dark.svg"> <img src="website/public/architecture-light.svg" alt="Architecture: AI clients use iphone-control mcp over stdio, and the optional control page serves browsers and remote agents over HTTPS; both talk to the daemon over a Unix socket. The daemon is the core: it drives the iPhone or iPad over USB, natively on iOS 27 and later and through WebDriverAgent on iOS 17–26, and keeps running with the control page closed" width="900"> </picture> </p>[!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.
Features
<p align="center"> <img src="docs/images/features.svg" alt="Device control (core): native on iOS 27+, 17 MCP tools, fewer round trips, runs unattended, a person in charge, doctor and alerts. Access: on this machine, remotely. Control page (optional)" width="900"> </p>Device control (core)
- See and touch the screen: screenshots with region zoom, tap, swipe, long-press, text input (including Chinese), hardware buttons
- Work with UI elements: read the element tree, tap by text (on a part not covered by floating bars or the keyboard), launch and close apps, open URLs, wait for text to appear
- Fewer round trips: any action can return the resulting screen once it has settled, say whether it changed, and flag pages still loading and blocking alerts;
iphone_batchruns up to 20 steps in one call - Runs unattended: recovers from replugging, phone reboots and lost connections, and keeps serving with the control page closed; a stuck WebDriverAgent is restarted and re-signed before it expires
- A person stays in charge: AI tasks can be paused, taken over or stopped at any time; paying, deleting or sending waits for your OK, and an agent can't approve its own task
- Several devices: connect several iPhones and iPads and switch which one is controlled
- Optional auto-unlock: every passcode digit is verified, and a wrong passcode disables auto-unlock after one attempt
- Alerts: Telegram or Bark notifications when the phone goes offline, a passcode is needed after a reboot, or re-signing fails
- Diagnostics:
doctorchecks every layer from USB up and tells you how to fix each failure
Access
- On this machine: Claude Code, Codex or any MCP client over stdio;
task runruns any agent platform in a task whose every step you can follow - Remotely: the viewer service serves HTTP MCP (
/mcp) on its port, over HTTPS with a login token (read-only ones too) when opened to the network;mcp --urlandtask --urluse a phone on another machine
Control page (optional)
- Live screen: on iOS 27 and later the phone's own video (about 60 fps), otherwise H.264; a low-bandwidth mode
- Act on it: the mouse taps and drags like a finger; system alerts missing from the video are drawn on it and can be tapped
- Hand out tasks: give a task to a local Claude Code or Codex, watch it work and take over at any time
Quick Start
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.sh
It 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-control
On 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-control
The 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.
MCP Tools
| 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. Screensh
Truncated for display — read the full file on GitHub.
Related Skills
Agent-Reach
113.0kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
hyperframes
86.4kAI video you can actually edit. HyperFrames is a free, open-source AI video editor. Describe any video and get a real project you can change down to the frame.
ruflo
82.0k🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
headroom
80.1kCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
