Skip to main content
Glama

πŸ€– droid-agent

Give any AI agent hands on a real Android device β€” zero install on the phone.

dump a screen β†’ get numbered interactive elements β†’ tap 3. That's it.

CI PyPI Python License: MIT

demo

Why

Every other Android-agent tool makes you install something on the phone first β€” an Appium server, a companion APK, an accessibility service. droid-agent needs nothing on the device. Just adb, which you already have:

  • πŸ”’ browser-use for Android β€” dump distills the uiautomator tree into a short numbered list of actionable refs, not a 500-line XML blob

  • πŸ“¦ zero dependencies β€” pure stdlib, installs in <1s, works offline

  • πŸ€– agent-first β€” every command has --json; ships a built-in MCP server

  • πŸ“± anything with adb β€” real phones, emulators, Android TVs, Android Auto, WSA, even Android-x86 VMs

Related MCP server: android-mcp

Install

pipx install droid-agent          # recommended
# or: pip install droid-agent

pipx install 'droid-agent[mcp]'   # + MCP server for Claude Code / Cursor / Devin

Prerequisite: platform-tools (adb) on your PATH, and a device with USB or wireless debugging enabled.

60-second tour

droid-agent devices                 # what's attached
droid-agent connect 192.168.1.42    # wireless adb (or just plug USB)
droid-agent dump                    # see the screen the way an agent does

Real output, straight off a POCO F5:

[ 1] ()    Search settings                                  ( 540, 497)
[ 2] |||   recyclerview                                     ( 540,1487)
[ 3] ()    About phone                                      ( 540, 663)
[ 4] ()    System apps updater                              ( 540, 817)
[ 5] ()    Security status                                  ( 540, 971)
[ 6] ()    Wi-Fi                                            ( 540,1159)
[ 7] ()    Bluetooth                                        ( 540,1313)
[ 8] ()    Mobile networks                                  ( 540,1467)
[ 9] ()    Interconnectivity                                ( 540,1621)

15 elements Β· tap with `droid-agent tap <ref>`
droid-agent tap 3                   # taps "About phone"
droid-agent type "me@x.com"         # types into the focused field
droid-agent swipe up                # scroll the list
droid-agent key back                # keyevents by name
droid-agent open com.whatsapp       # launch any app
droid-agent screenshot shot.png     # PNG capture
droid-agent state                   # foreground app, screen on/off, size

For agents, everything is one flag away from JSON: droid-agent --json dump.

Use it with your agent (MCP)

{
  "mcpServers": {
    "droid-agent": { "command": "droid-agent", "args": ["mcp"] }
  }
}

Tools exposed: devices, dump_ui, tap, tap_xy, type_text, swipe, key, open_app, close_app, device_state, screenshot, wait.

Commands

Command

What it does

devices

list attached devices + state

connect / pair / disconnect

wireless adb (Android 11+ pairing supported)

dump

numbered interactive elements β†’ ~/.droid-agent/session.json

tap <ref|x,y> / long-press

touch by ref from last dump, or raw coords

type <text>

input text (spaces handled) into focused field

swipe up|down|left|right or x1 y1 x2 y2

scroll / gestures

key back|home|enter|tab|del|power…

keyevents by name

open / close / install / uninstall

app lifecycle

screenshot / state

PNG capture Β· foreground app + screen info

shell <cmd>

raw adb escape hatch

mcp

stdio MCP server

How it compares

droid-agent

droidrun/mobilerun

mobile-mcp

Appium

On-device install

none

Portal APK + accessibility svc

Appium driver

Appium server + settings app

Time to first tap

seconds

minutes

minutes

~30 min

What it is

primitive layer

full agent framework

MCP bridge

test framework

Deps

0 (stdlib)

LLM SDKs, uv, portal

node, appium

java/node stack

LLM coupling

none β€” BYO agent

built-in providers

none

none

Different tool for a different job: they're agent frameworks; this is the curl of Android control β€” a primitive layer any agent (or human) can call.

Agent workflow pattern

dump β†’ read refs β†’ tap/type β†’ wait β†’ dump β†’ verify β†’ repeat

The dump warns when refs are >120s old (the UI may have moved). tap on a missing ref tells you to re-dump instead of tapping blind.

FAQ

Does it need root? No β€” just USB/wireless debugging enabled.

iOS? No. Use iphone-cli β€” this one is Android-only by design.

Passwords? Elements flagged password="true" are masked in dumps and never persisted to the session file.

CI? Point it at an emulator (emulator-5554) β€” same interface, --json for parsing.

Contributing

See CONTRIBUTING.md. Bug reports and false-positive element-detection reports especially welcome β€” attach droid-agent dump --json plus a screenshot.

License

MIT β€” see LICENSE.


Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Enables AI agents to control, inspect, and automate Android devices, Waydroid containers, and AVD emulators over ADB. Provides tools for screenshots, UI-hierarchy text-based tapping, gestures, key presses, text input, app management, and raw shell commands.
      12
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables an AI client to control an Android emulator or USB device over ADB by selecting a device, inspecting the UI hierarchy, and performing taps, swipes, text entry, key presses, and app launches. It relies only on Android platform-tools and exposes a compatible tool surface for phone automation.
      12
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to see and drive a real Android phone over plain ADB: screenshots and numbered UI trees, gestures, typing with accents and emoji, SMS/RCS reading and prepared replies, notifications, files, and settings, with no root and no app installed on the phone. Safeguards mask security codes and require explicit confirmation before sending, paying, deleting or confirming anything.
      18
      2
      MIT