# phonedriver [Health: Active]

**Category:** 🖥️ OS Automation  
**Repository:** https://github.com/hridaya423/phonedriver  
**GitHub Stars:** 149  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/phonedriver

## Description
MCP server and CLI that lets AI agents (Claude Code, Codex, Cursor) see and control Android phones and iPhones. Reads the screen as text. Asks before it pays.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "phonedriver": {
    "command": "npx",
    "args": ["-y","phonedriver"]
  }
}
```

## Documentation

## What phonedriver does

phonedriver gives an MCP-compatible AI client access to a connected Android or iOS device. Agents can read the current interface as structured text, identify controls by handles such as `@e24`, tap those controls, enter text, and request screenshots when visual content is necessary.

The server is suited to tasks that cannot be completed from a desktop alone. Examples include changing phone settings, working through an app's signup flow, checking onboarding in multiple display modes, finding reproducible bugs, and navigating a mobile website. It can also drive commerce flows while stopping for confirmation before a payment action.

## How it works

phonedriver runs as a standard MCP server over stdio, allowing an MCP client to launch it as a local process. The client sends actions to the device and receives a screen representation after the interface settles. Screen output is presented as a short numbered hierarchy of apps, buttons, switches, groups, and other visible elements.

Actions can refer to those numbered handles instead of requiring the model to estimate screen coordinates. Responses can report only the changes since the previous screen: added lines use `+`, removed lines use `-`, and changed lines use `~`. This keeps the device state compact for the agent. Screenshots are available for cases where text is not enough.

The underlying device can be an Android emulator, an Android phone connected with USB debugging enabled, or the iOS Simulator. The project also supports real iPhones through its installation workflow.

## Setup and configuration

The quick-start command registers the npm-delivered server with Claude Code:

```sh
claude mcp add phonedriver -- npx -y phonedriver mcp
```

A Homebrew installation is also available:

```sh
brew install hridaya423/tap/phonedriver
claude mcp add phonedriver -- phonedriver mcp
```

Claude Code and Codex can install phonedriver as a plugin. The plugin supplies the server and its skill together; it should not be used alongside a separate MCP registration, or the tools will appear twice. Cursor and VS Code have installation links in the project documentation.

On its first run, phonedriver downloads and caches a machine-specific binary for macOS, Linux, or Windows. Run `phonedriver doctor` to check adb, Xcode, and detected devices and to identify setup problems.

## Tools and capabilities

- Read the active phone screen as compact, numbered text.
- Tap controls by their returned element handles.
- Wait for the interface to settle before returning the result.
- Report only screen changes when an action produces a delta.
- Enter text on the device.
- Capture screenshots when visual inspection is required.
- Pause before tapping a payment control such as Buy with GPay.
- Drive Android phones, Android emulators, iPhones, and the iOS Simulator.

## Limitations and notes

A usable device environment is required: Android workflows need an emulator or a phone with USB debugging, while iOS workflows use the iOS Simulator or supported iPhone setup. Android and iOS dependencies such as adb and Xcode must be available where applicable.

The server is distributed under the AGPL-3.0 license. Its standard transport is local stdio rather than a hosted HTTP endpoint. Avoid registering the plugin and standalone MCP command at the same time, because that duplicates the exposed tools.

_Full upstream README: https://allmcps.com/mcp/phonedriver/readme_

