Documentation

Every command works from a terminal and as an MCP tool. Keep start running in one terminal and run the rest in another.

Quick start

Install the app. Turn on USB debugging, plug the phone in and run:
$npx android-agent-bridge usb
Start the bridge whenever you want the agent to have the phone:
$npx android-agent-bridge start
Connect your agent. In your project folder:
$npx android-agent-bridge init
For Claude Code you can also run claude mcp add phone -- npx -y android-agent-bridge.

Installation

The computer side needs Node.js 20 or newer. Run it with npx every time, or install it once to get the short phonectl command:

$npm i -g android-agent-bridge

The phone side is the Agent Bridge app (Android 5.0+). Install it with usb as above, or download the APK. After installing, Android asks you to switch on the Agent Bridge accessibility service; the app walks you there.

Pairing

Wi-Fi: phonectl and computer on the same network or hotspot. Run start, open the app, tap Scan and point it at the QR code. The app remembers the computer and reconnects by itself.

USB: usb sets up an adb tunnel, so no QR is needed and it works without Wi-Fi. On Windows, allow Node.js through the firewall the first time for Wi-Fi.

Targets

Commands that act on something take a target in one of four forms:

Target	Meaning
`12`	Element number from the latest element list. The most reliable.
`"Sign in"`	Visible text. The app's own controls win over the Android system bar, and text the app hides from accessibility is found by reading the screen.
`C7`	A grid cell from screen --mode grid, for maps, games and images.
`540,1200`	Screen pixels.

Commands

The examples use phonectl, which you get from the global install. With npx, write npx android-agent-bridge instead.

Setup

Command	What it does
`phonectl start`	Runs the bridge and prints the QR code to scan. A bigger one is at localhost:8350/pair.
`phonectl usb`	For a phone plugged in with USB debugging: installs the app, turns it on, pairs and runs the bridge. No QR code.
`phonectl wifi`	Same as usb without a cable (Android 11+): turn on Wireless debugging, scan the QR from Pair device with QR code. --code pairs with a code instead.
`phonectl init`	Adds the MCP server to .mcp.json and a short agent guide to the current project.
`phonectl pair`	Shows the QR code again. --reset makes a new secret; every phone must scan again.
`phonectl status`	The connected phone, how it is connected, and what it can do.
`phonectl permissions grant`	Over USB, switches on the optional permissions: brightness, rotation, Do Not Disturb, saving to Downloads.

Look

Command	What it does
`phonectl elements`	Numbered list of what's on screen. --all includes elements covered by sheets; --ocr adds text read from the pixels.
`phonectl screen --out shot.jpg`	Screenshot with every element boxed and numbered. --mode grid \| both \| plain.
`phonectl ocr`	All text drawn on screen, with positions.
`phonectl current`	The app in front.
`phonectl wait "Done"`	Waits until that text appears (--timeout 10000).

Act

Command	What it does
`phonectl tap 12`	Taps a target. --long long-presses.
`phonectl type "hello" --into 5`	Types into a field without the keyboard. --append keeps existing text, --submit presses Enter.
`phonectl scroll down`	Scrolls the main list. --in 3 picks a list, --amount 0.6 how far.
`phonectl swipe 540,1800 540,400`	Drags from one target to another (--ms 300).
`phonectl key back`	back, home, recents, notifications, quick_settings, enter, lock, power_dialog.

Apps & links

Command	What it does
`phonectl launch Uber`	Opens an app by name or package. --store opens its Play Store page if it isn't installed.
`phonectl apps whats`	Installed apps, filtered.
`phonectl url youtube.com`	Opens a web page or deep link (geo:, mailto:, myapp://).
`phonectl search "weather"`	Web search on the phone.
`phonectl store "Zepto"`	Play Store page or search.
`phonectl dial 9876543210`	Opens the dialer with the number filled in. Never places the call.
`phonectl stop com.example`	Force-stops an app (USB).

Device

Command	What it does
`phonectl volume 40%`	Media volume. Streams: ring, notification, alarm, call, system. Actions: up, down, mute, unmute, max, a level or a percentage.
`phonectl ringer vibrate`	normal, vibrate or silent.
`phonectl brightness 70`	0–100, auto or manual.
`phonectl rotation auto`	auto, portrait or landscape.
`phonectl flashlight on`	on or off.
`phonectl dnd on`	Do Not Disturb: on, alarms, total, off.
`phonectl settings wifi`	Opens a settings page: wifi, bluetooth, display, sound, battery, location, apps, developer and more.
`phonectl battery`	Level, charging, temperature, power saver.
`phonectl notifications`	Notifications received since the service started.
`phonectl clipboard set "text"`	Sets the clipboard; without set it reads it.
`phonectl wake`	Turns the screen on. A PIN lock stays locked.

Transfer

Command	What it does
`phonectl send a.pdf b.jpg`	Sends files to the phone's Downloads/Agent Bridge.
`phonectl received`	Files the phone sent, and the folder they're in (Downloads/Agent Bridge on the computer).
`phonectl drop`	Prints the drag-and-drop page address: http://localhost:8350/drop.

MCP tools

What your agent sees after init:

Tool	Purpose
`phone_status`	Connection, model, Android version; pairing help if nothing is connected.
`phone_elements · phone_screen · phone_ocr`	Read the screen as text, as a labelled screenshot, or from the pixels.
`phone_tap · phone_type · phone_scroll · phone_swipe · phone_key`	Act on the screen. Each returns the updated element list.
`phone_open_app · phone_apps · phone_wait_for`	Apps and waiting.
`phone_volume · phone_brightness · phone_toggle`	Sound, screen, flashlight, rotation, Do Not Disturb, ringer.
`phone_settings · phone_open_link · phone_web_search · phone_dial`	Jump to settings pages, links and the dialer.
`phone_device_info · phone_notifications · phone_clipboard · phone_wake`	Status and small utilities.
`phone_send_files · phone_received_files`	File transfer.
`phone_permissions · phone_stop_app`	Permissions over USB, force-stopping apps.

The server also offers six ready-made prompts (in Claude Code: /mcp__phone__do_in_app, /mcp__phone__test_my_app and others). See Get started for the list and more prompts to try.

Any MCP client works with this configuration:

{
  "mcpServers": {
    "phone": { "command": "npx", "args": ["-y", "android-agent-bridge"] }
  }
}

Troubleshooting

“App blocked to protect your device”: Play Protect blocks sideloaded accessibility apps opened from a browser or chat app. Install from your computer instead: npx android-agent-bridge usb, or with no cable on Android 11+, npx android-agent-bridge wifi.
No phone connected: is start running? Same Wi-Fi? On Windows, allow Node.js through the firewall. Over USB, run phonectl usb again to restore the tunnel.
Accessibility switch greyed out (Android 13+): App info → ⋮ → Allow restricted settings.
A tap opened nothing right after Home: Android holds app starts for about 5 seconds after Home. The commands retry, but run it again if needed.
Black screenshots: the app blocks capture (banking, video). Use elements instead.

Changelog

v0.1.4October 2026

usb waits a few seconds for a phone that adb has only just started to see, and tells you to tap “Allow” when the phone asks.
Clearer message when no phone is found over USB, pointing to wifi for cable-free setup.

v0.1.3October 2026

New wifi command: install and pair over Wi-Fi with Android 11+ wireless debugging, no cable.
usb and wifi download Google's adb tool by themselves when the computer doesn't have it.
The website's download buttons now lead to the install guide, so nobody hits Play Protect's block.

v0.1.2October 2026

Six built-in MCP prompts (in Claude Code: /mcp__phone__do_in_app, /mcp__phone__test_my_app and more).
New Get started guide with a prompt library, and a rewritten README.

v0.1.1October 2026

QR scanner is now a portrait pop-up that slides up from the bottom, with a flash button.
Recent transfers: tap a file to open it, delete received files from the phone, clear the list.
Open folder button jumps to the received files (Samsung My Files opens right at the folder).

v0.1.0October 2026 · first public release

Android app (5.0+) with QR pairing over Wi-Fi and USB, Connect / Transfer / Device tabs.
CLI and MCP server with 30+ tools: screen reading, taps, typing, gestures, apps, device controls.
On-device OCR for text apps hide from accessibility; occlusion-aware element lists.
File transfer both ways, with a drag-and-drop page at localhost:8350/drop.