# Questions about phonedriver

> Short answers about setup, real phones, speed, tokens, other tools, approval before paying and telemetry.

Web page: https://phonedriver.dev/faq/

## What it is

### What is phonedriver?

phonedriver is a free, open-source CLI and MCP server that gives an AI agent a text view of an Android or iOS screen and the means to tap, type and swipe. Every action waits for the screen to settle and returns only the lines that changed, so the agent does not poll or sleep. It is licensed AGPL-3.0.

### What does it cost, and what is the license?

It is free. The license is AGPL-3.0-only: if you distribute phonedriver, or run a modified version as a network service, you must publish your source under the same license. The Android agent contains files copied from scrcpy under Apache-2.0.

### Can I use it at work?

Yes. It is AGPL-3.0: you can use it freely. If you change it and offer it to others as a network service, you must publish your changes.

### Is phonedriver the same as PhoneDriver by OminousIndustries?

No. The two share a name and nothing else. PhoneDriver by OminousIndustries is a Python agent that looks at screenshots with a Qwen3-VL vision model and drives an Android phone over adb, by its README. phonedriver, this project, is an MCP server and CLI in Rust at github.com/hridaya423/phonedriver. It brings no model: it gives the agent you already use a text view of an Android or iOS screen.

## Set it up

### How do I let an AI agent control my phone?

Install phonedriver, add it to your agent as an MCP server (claude mcp add phonedriver -- npx -y phonedriver mcp for Claude Code), connect an Android phone with USB debugging, start an emulator, or boot the iOS Simulator, and ask the agent in plain language, for example "Open Settings and turn on dark mode." The agent gets a text view of the screen and tools to tap, type and swipe. See the setup guides.

### How do I let Claude control my Android phone?

Add phonedriver to Claude Code as an MCP server with claude mcp add phonedriver -- npx -y phonedriver mcp, then connect a phone with USB debugging on or start an emulator. Nothing is installed on the phone. It is tested on emulators (API 26 and 37) and on a HONOR X8 (Android 13). See the Claude Code guide.

### Can Codex or Cursor control a phone?

Yes. Codex: codex mcp add phonedriver -- npx -y phonedriver mcp. Cursor and any other client that starts a stdio MCP server: command npx, args -y phonedriver mcp. An agent with only a shell can run the same commands, such as npx -y phonedriver snapshot. Claude Code is the client I test against; see Cursor and other clients.

### Which AI agents and MCP clients work with it?

Any client that starts a stdio MCP server can use it, including Claude Code and Cursor. Claude Code is the one I test against, with claude -p and Claude Sonnet 5.5 in my benchmarks. I have not run a Cursor session myself. The server has fourteen tools, and the CLI prints the same text as the MCP tools.

### Does it work with VS Code, Gemini CLI, Zed or Cline?

It is a standard MCP server over stdio, so any client that starts one can run it. I test with Claude Code and have not run a session in the others. The entry for each, written from that client's own documentation, is in Codex, VS Code and Cursor and other clients. The approval prompt needs a client that supports MCP elicitation.

### Does it run on Windows and Linux?

Yes for Android. Each release has binaries for macOS, Linux and Windows, and npx -y phonedriver downloads the one for your machine. iOS needs a Mac with Xcode, for the Simulator and for an iPhone.

## Phones

### Does it work on a real iPhone and a real Android phone?

Yes for iPhone and iPad through the CLI and MCP, tested on an iPhone 13 Pro Max (iOS 27.0.1), an iPhone 14 Plus (iOS 26.1) and an iPad Pro (iOS 27.0). It needs a Mac with Xcode and an Apple Development certificate: phonedriver ios setup reads the signing team from it, so there is no team ID to look up, then builds and starts the runner. After phonedriver ios wifi on the cable can come off while the iPhone shares a Wi-Fi network with the Mac. A real Android phone uses the same path as the emulator, over USB or Wi-Fi debugging; a HONOR X8 (Android 13) is the one phone tested so far. Android emulators (API 26 and 37) and the iOS Simulator are tested.

### Does it install anything on my phone?

On Android, no app and no accessibility service. The daemon pushes a small jar over adb and starts it with app_process as the shell user, the way scrcpy does. On iOS, a small XCTest runner is built on your Mac with Xcode the first time it is needed.

### Does it need root or a jailbreak?

No. On Android the agent runs as the shell user, started over adb with app_process, the way scrcpy starts its server. On iOS it is an XCTest runner that Xcode builds and signs with your own Apple developer team.

### Does phonedriver use WebDriverAgent or Appium on iOS?

No. It builds its own small XCTest runner on your Mac. WebDriverAgent is an XCTest runner too, so the mechanism is the same; mine leaves out the WebDriver HTTP server, the XPath engine and the session model. On an iPhone 17 simulator the runner read a screen 2.0 times faster than fully tuned WebDriverAgent at p50, and 8 to 19 times faster than WebDriverAgent with only snapshotMaxDepth set. It needs what any XCTest runner needs: a Mac with Xcode, and an Apple Development certificate for a real iPhone. See phonedriver vs Appium and the iPhone guide.

### Can the agent work without taking over my screen?

On Android 13 and later, yes. Set PHONEDRIVER_DISPLAY=hidden in the MCP config, or pass --display hidden to the CLI, and the agent works on a hidden second screen while yours stays as it is. It has been tested on an emulator and on a HONOR X8. Typing into a web page shows the system's clipboard note, and your clipboard is put back after.

## Speed and tokens

### What is the fastest way for an AI agent to control a phone?

On an Android 17 emulator, phonedriver reads a 1,000-row list in 12.7 ms where adb takes 2,163.7 ms (170 times faster at p50, 95% CI 162.0 to 177.4), takes a screenshot in 9.1 ms against 291.2 ms (32 times) and types 100 characters in 158.3 ms against 3,638.4 ms (23 times). A bare tap is closer: 2.4 to 4.4 times faster host to reply. On a HONOR X8 phone (Android 13), reading the screen took 78.5 ms against 2,507 ms (32 times) and a screenshot 16 ms against 1,006 ms (61 times). See the benchmarks.

### Why is uiautomator dump slow, and what is faster?

uiautomator dump is a one-off command: every call starts a process, connects to the accessibility service and waits for the screen to go idle. On one Android 17 emulator it took 2,163.7 ms to read a 1,000-row list (p50 of 50 runs, 11 November 2026). phonedriver keeps a small agent on the device with that connection open, and read the same list in 12.7 ms. The Settings screen took 51.0 ms, and on a HONOR X8 phone the read took 78.5 ms against 2,506.6 ms. The fairer rival is a server that stays resident, such as Appium's UiAutomator2 server, and I did not measure that. I also did not split adb's time between process start and the idle wait. See phonedriver vs adb.

### How many tokens does it use?

On nine real phone jobs with Claude Sonnet 5.5 on one Android emulator (10 November 2026), phonedriver used 657,542 tokens and passed 27 of 27 runs. mobile-mcp used 4,567,200 (6.9 times as many) and passed 17 of 18. phone-harness used 1,127,495 and passed 14 of 18, and used fewer tokens than phonedriver on two of the nine jobs. The 14 MCP tools cost about 5,600 tokens on the first turn of a one-word claude -p. Small samples: see the benchmarks.

### What is the best MCP server for controlling a phone?

On my benchmark of nine real phone jobs (Claude Sonnet 5.5, one Android emulator, 10 November 2026), phonedriver passed 27 of 27 runs with 657,542 tokens. mobile-mcp passed 17 of 18 with 4,567,200 tokens, 6.9 times as many, and phone-harness passed 14 of 18 with 1,127,495. It also reads a 1,000-row list 170 times faster than adb on that kind of emulator. I wrote the jobs, so read the method and raw data before you trust the ranking.

## Other tools

### Is there an alternative to mobile-mcp?

phonedriver is one. Both are MCP servers for Android and iOS. On nine real phone jobs mobile-mcp used 6.9 times the tokens of phonedriver, and phonedriver adds a diff after every action, an approval prompt before a tap that spends money, and no telemetry, where mobile-mcp sends anonymous usage data by default. mobile-mcp supports cloud devices and phonedriver does not. See phonedriver vs mobile-mcp.

### How is phonedriver different from mobile-mcp and phone-harness?

mobile-mcp is an MCP server that reads the accessibility tree and also supports cloud devices, with anonymous telemetry on by default. phone-harness is a Python CLI that drives Android through adb and iPhones through Mac mirroring and OCR. phonedriver keeps a resident agent on the Android device, waits for the screen to settle after every action and returns a diff, asks before taps that spend money, and sends no telemetry. See the comparisons.

### Is phonedriver an Appium alternative for AI agents?

For an agent that decides each step from the screen, yes. Appium is a WebDriver server built for scripted tests: it installs a helper app on the device and answers with XML page source. phonedriver installs nothing on Android, gives the model a short numbered text screen, and returns only what changed after each action. For a fixed test suite in CI, Appium is still the usual tool. I have not benchmarked phonedriver against Appium on Android. On an iOS simulator my runner read a screen 2.0 times faster than fully tuned WebDriverAgent, the runner Appium uses. See phonedriver vs Appium.

## Testing apps

### Can an AI agent test my React Native, Expo or Flutter app with it?

It can install a build, open it and use it the way a person would, because phonedriver drives whatever is on the screen. It reads the accessibility tree the system exposes and falls back to OCR where that tree is empty. On my benchmark, Claude Sonnet 5.5 found both planted bugs in a native Android testbed's sign-up form in 3 of 3 runs, with a median of 121,854 tokens (10 November 2026). I have not tested a React Native, Expo or Flutter app, so run phonedriver snapshot on yours first and read what it lists. See testing a mobile app.

### Can it run with nobody watching?

Yes, and the benchmarks on this site ran that way: claude -p against an emulator started with -no-window. In a headless run nobody can answer the approval prompt, so a tap on Pay or Place order gets no answer and nothing is tapped. For unattended runs, use an emulator or a spare phone.

## Safety and privacy

### Can the agent spend my money or delete things?

Not without asking you. Before a tap on a button such as Place order, Pay, Send $20.00 or Delete account, phonedriver stops and asks the human through the MCP client, showing the app, the button and the amounts on screen. Sending, deleting and installing are asked about too when you set PHONEDRIVER_ASK. This stops an agent that follows its rules or is steered by screen text; it does not stop one set on bypassing it, and it reads labels in eleven languages, not icons. See the approval guard.

### Does phonedriver send telemetry?

No. It talks to the device, the local daemon socket and the local adb server, and to Apple only when mounting an iOS developer disk image. A test runs the CLI, daemon and MCP server under a macOS sandbox that kills any process opening a non-local connection. Text passed with --secret never reaches logs, traces or replies. This website sets no cookies and loads no third-party scripts.

### What does it not do well yet?

A bare tap misses its 15 ms budget. An iOS tap takes 454 to 534 ms on devices; on the Simulator, since 0.1.5, a tap with its reply takes 316 ms. WebViews and custom views can have an empty accessibility tree, where it falls back to OCR. The real-phone jobs benchmark ran two or three passes per job on one tablet emulator, so its medians describe what happened and are not rates. One Android phone model, a HONOR X8, has been tested.
