Get started

From nothing to “open YouTube on my phone” in about five minutes. Every command on this page has a copy button.

What you need

An Android phoneAndroid 5.0 or newer, any brand

A computerWindows, macOS or Linux with Node.js 20+

A USB cableOnly for the first install

An AI agentClaude Code, Cursor, Antigravity or any MCP client

1 · Install the app

Recommended: over USB. On the phone, open Settings → About phone and tap Build number seven times. Then go to Settings → Developer options and turn on USB debugging. Plug the phone in and run:

$npx android-agent-bridge usb

This installs the app, switches on its accessibility service, pairs it and starts the bridge. Accept the “Allow USB debugging?” prompt on the phone. You can skip step 2.

No cable? Over Wi-Fi (Android 11+): in Developer options turn on Wireless debugging, run this, then tap Pair device with QR code on the phone and scan the code in your terminal.

$npx android-agent-bridge wifi

Both commands fetch Google's adb tool the first time if your computer doesn't have it.

Why not the APK? Google Play Protect blocks sideloaded apps that use the accessibility service when they're opened from a browser or chat app (“App blocked to protect your device”). Installing from your computer isn't affected. If your phone allows it, the APK (13 MB) works too.

2 · Start and pair

Skip this if you used usb. Otherwise, with the phone and computer on the same Wi-Fi:

$npx android-agent-bridge start

Open Agent Bridge on the phone and tap Scan QR code.
Point the camera at the QR code in your terminal, or the bigger one at localhost:8350/pair.
Tap Accessibility service → Turn on in the app and switch Agent Bridge on.

The app remembers your computer and reconnects by itself. On Windows, allow Node.js through the firewall when asked.

3 · Connect your agent

Claude Code:

$claude mcp add phone -- npx -y android-agent-bridge

Any project (writes .mcp.json and a short agent guide):

$npx android-agent-bridge init

Cursor, Antigravity, Windsurf and other MCP clients: add this to the client's MCP config file (Cursor: .cursor/mcp.json).

mcp.json

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

Restart the agent after adding it. It gets 27 tools such as phone_screen, phone_tap and phone_type, plus the prompts below.

4 · Check it works

Ask your agent:

Or from a terminal: install the short command once, then check the status.

$npm i -g android-agent-bridge

$phonectl status

Prompts to try

Click any prompt to copy it, then paste it into your agent. Agents are told to ask you before sending, paying, posting or deleting.

First five minutes

Check everything works and get a feel for it.

Everyday

Hands-free help with apps you already use.

For developers

Test and debug the Android app you are building.

Files

Move files between the computer and the phone.

Built-in MCP prompts

The MCP server also ships ready-made prompts. In Claude Code they're slash commands: type /mcp__phone__ to see them. Other clients list them in their prompt menu.

Slash command	Asks for	What it does
`/mcp__phone__phone_tour`	nothing	Confirms the phone is connected and describes the screen.
`/mcp__phone__do_in_app`	app, task	Opens an app and carries out a task step by step.
`/mcp__phone__test_my_app`	app, focus?	QA walkthrough with a bug report at the end.
`/mcp__phone__catch_up`	nothing	Summarises notifications, urgent first.
`/mcp__phone__set_up_phone`	settings	Volume, brightness, Do Not Disturb in one go.
`/mcp__phone__send_to_phone`	files	Sends files and confirms where they landed.

Command cheat sheet

Everything an agent can do, you can do from a terminal. phonectl comes with npm i -g android-agent-bridge; without it, use npx android-agent-bridge. Keep start running in another terminal.

Set up

`npx android-agent-bridge usb`	Install the app over USB, switch it on, pair, start
`npx android-agent-bridge start`	Start the bridge and show the pairing QR code
`npx android-agent-bridge init`	Add the MCP server to this project
`phonectl status`	Is the phone connected?

Look and act

`phonectl screen --out shot.jpg`	Screenshot with numbered elements
`phonectl elements`	Numbered list of what's on screen
`phonectl tap 12`	Tap element 12 (or "Sign in", C7, 540,1200)
`phonectl type "hello" --into 5 --submit`	Type into a field and press Enter
`phonectl scroll down`	Scroll the main list
`phonectl key back`	back, home, recents, notifications

Apps and device

`phonectl launch YouTube`	Open an app by name
`phonectl volume 40%`	Media volume (ring, alarm, …)
`phonectl brightness 70`	Screen brightness, or auto
`phonectl dnd on`	Do Not Disturb
`phonectl battery`	Battery level and charging

Files

`phonectl send photo.jpg`	Send to the phone's Downloads/Agent Bridge
`phonectl received`	Files the phone sent to this computer
`phonectl drop`	Drag-and-drop page in the browser

Every command, with all its options, is in the full command reference.

If something's wrong

“App blocked to protect your device”: install over USB with npx android-agent-bridge usb.
The agent says no phone is connected: is start (or usb) running? Same Wi-Fi? Is the accessibility service on in the app?
Accessibility switch is greyed out (Android 13+): App info → ⋮ → Allow restricted settings, then try again.
Screenshots are black: that app blocks screen capture (banking, video). The agent can still read the element list.

Still stuck? Open an issue on GitHub.