# phonedriver

> phonedriver is an open-source MCP server and CLI that lets AI agents like Claude Code see and control Android and iOS phones. It shows a screen as numbered text, and every tap, type or swipe returns only the lines that changed.

phonedriver is a free, open-source (AGPL-3.0) CLI and MCP server. It runs on macOS, Linux and Windows and controls Android emulators and phones, the iOS Simulator and iPhones. It sends no telemetry. Numbers below come from benchmarks on an Android 17 emulator and a HONOR X8 phone; each page links its method and raw data.

## Set up

Needs Node 18 or later. The first run downloads one binary and caches it.

1. Add the MCP server. Claude Code: `claude mcp add phonedriver -- npx -y phonedriver mcp`. Codex: `codex mcp add phonedriver -- npx -y phonedriver mcp`. Any other client: a stdio server with command `npx` and args `["-y", "phonedriver", "mcp"]`.
2. Run `npx -y phonedriver doctor`. Each line says ok, warn or fail, and a fix follows every line that is not ok.
3. Run `npx -y phonedriver devices`. With no device listed, start an Android emulator, plug in a phone with USB debugging on, or boot an iOS Simulator.
4. An agent with a shell and no MCP can use the same commands directly: `npx -y phonedriver snapshot`, `npx -y phonedriver tap @e4`. The text is the same as the MCP tools return.

## Operate

- `npx -y phonedriver skill` prints the instructions an agent should read before it uses the tools. Read it first.
- `snapshot` lists the screen as lines such as `@e4 button "Save"`. Act on a ref (`tap @e4`). Every action waits for the screen to settle and returns only the lines that changed, so do not sleep, poll or call `snapshot` after each action.
- A tap on Pay, Buy now, Place order, Transfer or Delete account is held until the human approves it (CLI exit code 5). Do not work around it; ask the human.
- Exit codes: 0 done, 1 failed, 2 wrong command line, 3 a person must act on the device, 4 no matching device, 5 needs the human's approval.
- Text for a password or a one-time code goes through `type` with `secret`, never as a plain argument.

## Docs

Each link is the page as Markdown. Drop `index.md` for the web page.

- [How to install phonedriver](https://phonedriver.dev/docs/install/index.md): Set up phonedriver by pasting one prompt into your agent, or install the binary by hand on macOS, Linux or Windows and check it with phonedriver doctor.
- [How to use phonedriver with Claude Code](https://phonedriver.dev/docs/claude-code/index.md): Add phonedriver to Claude Code as an MCP server with one command, point it at a device and ask it to operate a phone in plain language.
- [How to use phonedriver with Cursor and other MCP clients](https://phonedriver.dev/docs/cursor-and-mcp-clients/index.md): Add phonedriver to Cursor or any MCP client that starts a stdio server, with a JSON entry, an optional device setting and the list of tools it exposes.
- [How to control an Android emulator with phonedriver](https://phonedriver.dev/docs/android-emulator/index.md): Start an Android emulator, check phonedriver sees it, and drive it. Includes the headless flags used in the benchmarks and how to use an emulator on another machine.
- [How to control a real Android phone with phonedriver](https://phonedriver.dev/docs/android-phone/index.md): Turn on USB debugging or Wi-Fi debugging, connect an Android phone or tablet, and let an agent operate it with phonedriver. Notes on what has and has not been tested.
- [How to control the iOS Simulator with phonedriver](https://phonedriver.dev/docs/ios-simulator/index.md): Boot an iPhone Simulator on a Mac and let an agent drive it with phonedriver. Needs Xcode and XcodeGen. Covers the first-run runner build and the Simulator's tap latency.
- [How to control a real iPhone or iPad with phonedriver](https://phonedriver.dev/docs/iphone/index.md): Pair an iPhone or iPad, set up Developer Mode and a signing team, and let an agent drive it with phonedriver. Tested on an iPhone 14 Plus and an iPad Pro.
- [How to keep an AI agent from spending your money on a phone](https://phonedriver.dev/docs/approval-guard/index.md): phonedriver stops taps on Pay, Place order and Delete account and asks you first. How the guard works, how to answer, how to switch it off for full autonomy, and what it does not catch.
- [How to run device commands with the phonedriver shell](https://phonedriver.dev/docs/shell/index.md): Run a setting, intent or key on the device in one call with phonedriver shell, and see the exit code, the output and what changed on screen. Android, iOS Simulator and physical device rules.
- [How to troubleshoot phonedriver](https://phonedriver.dev/docs/troubleshooting/index.md): Start with phonedriver doctor, then read the daemon log and traces. Exit codes, what each means, and the errors seen most often with another UiAutomation client, WebViews and device setup.

## Benchmarks

- [Benchmarks](https://phonedriver.dev/benchmarks/index.md): real phone jobs on 10 November 2026 (27 of 27 runs for phonedriver, 17 of 18 for mobile-mcp at 6.9 times the tokens, 14 of 18 for phone-harness); speed against adb and phone-harness with p50, p95 and confidence intervals
- [Raw job runs](https://phonedriver.dev/benchmarks/data/jobs.json)
- [Raw speed samples](https://phonedriver.dev/benchmarks/data/speed-samples.csv)

## Comparisons

- [phonedriver vs adb](https://phonedriver.dev/compare/adb/index.md): phonedriver against plain adb on an Android emulator. 170x faster UI tree reads, 32x faster screenshots, 23x faster typing, and a bare tap that is 2.4 to 4.4 times faster. A HONOR X8 phone gave 32x and 61x on two operations. What adb still does better.
- [phonedriver vs mobile-mcp](https://phonedriver.dev/compare/mobile-mcp/index.md): Two MCP servers that let an AI agent control a phone. On nine real phone jobs on one emulator, mobile-mcp used 6.9 times the tokens of phonedriver and passed 17 of 18 runs against 27 of 27. What each reads, installs, waits for and sends, and what I have not measured.
- [phonedriver vs phone-harness](https://phonedriver.dev/compare/phone-harness/index.md): On nine real phone jobs phonedriver passed 27 of 27 runs and phone-harness 0.3.3 passed 14 of 18, using 1.7 times the tokens and 4.4 times the time. Per operation phonedriver was 2.4 to 186 times faster. Measured on one emulator, with how each tool drives a phone and what each sends home.

## Blog

- [How phonedriver reads a phone's screen 170x faster than adb](https://phonedriver.dev/blog/how-phonedriver-reads-a-screen-170x-faster-than-adb/index.md): The on-device agent, UiAutomation, an H.264 stream and frame-change detection behind phonedriver's 12.7 ms read of a 1,000-row list against 2,163.7 ms for adb, the fixes I measured, and how I measured them.
- [phonedriver vs mobile-mcp vs phone-harness vs adb: benchmarked on real phone jobs](https://phonedriver.dev/blog/phonedriver-vs-mobile-mcp-vs-phone-harness-vs-adb-real-phone-jobs/index.md): The method and results of a benchmark that gives Claude nine jobs only a phone can do, with phonedriver, mobile-mcp, phone-harness and adb, rerun on 10 November 2026 on one emulator. phonedriver ran each job three times and the others twice.
- [Letting Claude order dinner without letting it spend your money](https://phonedriver.dev/blog/letting-claude-order-dinner-without-letting-it-spend-your-money/index.md): How phonedriver's approval guard stops an agent's tap on Place order or Pay and asks you first through MCP elicitation, what it covers, what it does not, and why the limits are in the design record.
- [Benchmarking AI agents on jobs only a phone can do](https://phonedriver.dev/blog/benchmarking-ai-agents-on-jobs-only-a-phone-can-do/index.md): How to design a phone-agent benchmark that is fair to every tool. Jobs a shell cannot do, checks from device state, no model as judge, and why adb and web searches are excluded from the core set.

## Optional

- [Full text of this site](https://phonedriver.dev/llms-full.txt)
- [Source code and design decisions](https://github.com/hridaya423/phonedriver)