hridaya423/phonedriver
AI EngineeringMCP server and CLI that let AI agents read and control Android phones and iPhones with a confirmation step before payments.
What it does
phonedriver is a standard MCP server over stdio plus a matching CLI that gives an AI agent control over an Android phone, an Android emulator, the iOS Simulator, or a real iPhone/iPad. The agent reads each screen as a short numbered text list and taps elements by number, so it does not need to parse images or poll for screen loads. A daemon keeps the device connection open and tracks which @e identifier maps to which element, so taps still land after a list shifts.
The project targets agent workflows that only a phone can do: ordering on a real site, walking an app's onboarding, or hunting bugs in a sign-up flow. It works with Claude Code, Codex, Cursor, VS Code and other MCP clients.
Quick start
Install the MCP server into Claude Code:
claude mcp add phonedriver -- npx -y phonedriver mcp
Alternatives are a Homebrew binary or a plugin that adds the server and its skill together; use one path only, or tools are listed twice. Cursor and VS Code have one-click install links in the README.
Before giving the agent a job, start an Android emulator, plug in an Android phone with USB debugging on, or boot the iOS Simulator. Then run phonedriver doctor to check adb, Xcode and the connected devices and see what needs fixing. With a device ready, give the agent a phone task in natural language.
The first run downloads one binary for the machine (macOS, Linux or Windows) and caches it. Shell and PowerShell installers, real iPhone setup and per-client configuration are covered in the install guide and reference.
Reading the screen
The CLI prints screens in a compact text form:
$ phonedriver snapshot
app com.android.settings (Settings) · keyboard hidden · settled in 0ms
@e1 button "Search Settings"
@e2 group scrollable↓
@e3 button "Google" "Services & preferences"
After a tap, only the changes come back, marked with + for appeared, - for removed and ~ for changed. A screenshot is taken only when the model needs an image.
Approval guard
When a tap lands on a button labeled Pay, Buy now, Buy with GPay, Place order, Start subscription, Transfer or Delete account, phonedriver holds the tap and asks the human in the client's own prompt. The model cannot see or answer that question. You can select Allow, Allow for this session, or Decline.
PHONEDRIVER_ASK extends the check to send, delete and install button types. Autonomous runs are possible via autonomous: true in agent instructions, or by turning the check off with PHONEDRIVER_GUARD=off. The label check covers English, Spanish, Portuguese, French, German, Italian, Dutch, Japanese, Chinese (Simplified), Korean and Hindi, but misses icon-only payment buttons and labels in other languages.
Requirements and limits
The Android path needs adb; for a physical device USB debugging must be on. iOS Simulator needs a Mac with Xcode, and a real iPhone or iPad additionally needs an Apple Development certificate and phonedriver ios setup. Android requires no app install: phonedriver pushes a helper over adb. On iOS it builds an XCTest runner on the Mac.
After setup the cable can be removed: phonedriver ios wifi on for iPhone, phonedriver pair or phonedriver untether for Android. On Android 13 and later, --display hidden or PHONEDRIVER_DISPLAY=hidden lets the agent work on a hidden second screen.
The agent has the same reach as a finger: it cannot enter a passcode or pass Face ID/fingerprint, and commands stop on a locked phone. Screenshot-blocking apps come out black in screenshots, though their text can still be read. The API has 14 MCP tools (devices, apps, snapshot, screenshot, tap, type, swipe, scroll, press, launch, wait, batch, clipboard, shell), with three marked read-only. A device used from a terminal passes to the agent after 30 seconds idle. The license is AGPL-3.0-only; network service use of modified code requires publishing changes, and the OpenH264 build carries no H.264 patent license.
HotRepo's take
On 10 November 2026 the README reports a self-run comparison on nine phone jobs: 27 of 27 runs passed with 658 thousand tokens in 5.1 minutes, versus 4.6 million tokens for mobile-mcp and 1.1 million for phone-harness, with all three tools on the same Android emulator and Claude Sonnet 5.5. That is the author's own test set and hardware; the raw runs and checks are published in the benchmark notes. The separate speed test on an Android 17 emulator reports screen reads at 13 ms versus 2,164 ms for adb shell uiautomator dump, a median over 50 runs, with method and raw data in the speed notes.
HotRepo's own star sampling shows slow but steady growth in the 24 hours through 2026-11-15, from 100 to 125 stars, with no recorded GitHub daily-wide ranking. The practical question is the safety model: the approval guard is a useful default, but it reads button labels rather than transaction state, so the guard's language coverage and icon-only limitation matter when an agent is allowed anywhere near a checkout.
Written by AI from the project's README, updated . The project's own docs are the source of truth.
You might also like
- phone-harness/mcpA hosted MCP server that lets AI agents control real iPhones and Android emulators in the cloud.
- callstack/agent-deviceA CLI, MCP server, and typed Node.js API that let AI coding agents inspect, control, and verify apps on mobile, TV, web, and desktop devices.
- JosssphZhou/pokiLet Claude Code, Codex, or other MCP clients drive a real iPhone from a Mac, without jailbreak or extra hardware.
- ZSeven-W/dsh-iosGives coding agents 22 tools to boot, build, and drive iOS Simulators or USB-connected iPhones, with a live interactive sidebar.
- ZSeven-W/dsh-androidDeepSeek Harness plugin that streams a live Android emulator or USB device into the conversation and drives it through adb.