Skip to main content
Glama

Python 3.11+ License MIT MCP Compatible PyPI MCP Registry Awesome PyPI Downloads LinkedIn Ask DeepWiki

Agent Droid Bridge

Agent Droid Bridge is an MCP server that connects AI agents to Android devices and emulators over ADB. It is built for mobile automation, app testing, dynamic analysis, and reverse engineering: exposing the full surface of ADB as structured tools that any MCP-compatible AI client can call directly. If ADB can do it, an agent can do it.


Purpose-built tools return structured, minimal responses. No raw XML dumps, no wasted context — agents stay fast across long sessions.

agent-droid-bridge MCP server

Demo

Agent Droid Bridge Demo

The demo above runs through a few straightforward tasks to show what a connected agent can do, and this is just scratching the surface:

  • Installs the Paint app, opens it, and draws a house by calculating pixel coordinates for the walls and roof

  • Opens the device browser, searches for "MCP Wikipedia", navigates to the result page, and takes a screenshot

  • Opens the Calculator, computes 1337 × 42, and extracts the result to the host machine

  • Opens Contacts, creates a new entry with a name and phone number, and confirms it saved

  • Opens the Calendar and schedules an appointment for a specific date

  • Opens Settings and toggles dark mode

  • Extracts the Calculator APK from the device to the host machine

  • Installs Notepad, writes a one-sentence summary of every task completed, and takes a final screenshot

Related MCP server: scrcpy-mcp

What it does

Tools

  • 14 built-in tools for screen capture, UI inspection, text reading, element extraction, touch and swipe input, text entry, keycode events, app launching, ADB commands, and device inspection

  • app_manager pack adds 9 tools for package management, app lifecycle, APK extraction, permissions, and intent injection. Load it with ADB_EXTRA_TOOL_PACKS=app_manager

  • Tool availability is reflected in the server's startup instructions. Agents receive an accurate catalog at connect time

Device handling

  • Auto-detects a single connected device; prompts for selection when multiple devices are present

  • Runs over stdio, compatible with any MCP-capable AI client

  • Structured responses instead of raw XML dumps, keeping agent context lean across long automation runs

Security

  • Two execution modes: unrestricted (full ADB access, optional denylist) and restricted (allowlist-only, blocks everything not explicitly permitted)

  • Set ADB_ALLOW_SHELL=false to disable all shell commands regardless of mode

  • Hide specific tools from the agent with ADB_DENIED_TOOLS

  • All commands parsed via shlex. No shell injection possible

Observability

  • Optional session recorder logs every tool call, ADB command, and security event to structured JSONL files. Enable with MCP_LOG_ENABLED=true and MCP_LOG_DIR

Use cases

Mobile QA and test automation Automate UI flows across real devices and emulators without modifying the app or writing test code. Tap, swipe, type, read screen content, take screenshots — all from a natural language prompt.

App security research Extract APKs, inspect declared permissions, fire arbitrary intents, and observe runtime behavior on screen. No instrumentation, no jailbreak required.

Dynamic analysis Launch apps in controlled states, drive UI interactions, capture screen state at each step, and pull artifacts — all scriptable through an AI agent.

Development and debugging Install builds, verify UI states, check app info, and run ADB commands without leaving your coding environment.

Install

uvx agent-droid-bridge

No cloning or virtual environments needed. Requires Python 3.11+ and ADB installed on your host.

uvx is provided by uv. If you don't have it: curl -LsSf https://astral.sh/uv/install.sh | sh

To install from source instead, see docs/setup.md — Option B.

To verify the install: uvx agent-droid-bridge --help

Quick start

  1. Install ADB — see docs/setup.md for platform-specific instructions

  2. Connect an Android device or start an emulator

  3. Add the server to your MCP client config:

{
  "mcpServers": {
    "agent-droid-bridge": {
      "command": "uvx",
      "args": ["agent-droid-bridge"],
      "env": {
        "ADB_EXECUTION_MODE": "unrestricted",
        "ADB_ALLOW_SHELL": "true",
        "ADB_PATH": "adb",
        "ADB_EXTRA_TOOL_PACKS": "",
        "MCP_LOG_ENABLED": "false",
        "MCP_LOG_DIR": "~/logs/agent-droid-bridge"
      }
    }
  }
}

To enable session logging, set MCP_LOG_ENABLED to "true" and update MCP_LOG_DIR to a writable path on your machine.

Variable

Default

Description

ADB_EXECUTION_MODE

unrestricted

Security mode. unrestricted allows all shell commands (with optional denylist); restricted allows only commands in ADB_SHELL_ALLOWLIST.

ADB_ALLOW_SHELL

true

Set to false to block all adb shell commands regardless of execution mode.

ADB_PATH

adb

Path to the ADB binary. Replace with a full path if adb is not on your system PATH (e.g. C:\platform-tools\adb.exe on Windows).

ADB_EXTRA_TOOL_PACKS

(empty)

Comma-separated list of extra tool packs to load. Set to app_manager to enable 9 additional app management tools.

MCP_LOG_ENABLED

false

Set to true to enable session logging. Requires MCP_LOG_DIR.

MCP_LOG_DIR

(none)

Directory where session logs are written. Required when MCP_LOG_ENABLED is true.

  1. Prompt your agent to use the agent-droid-bridge MCP tools

Full setup guide and environment variable reference: docs/setup.md

Tools

Tool

What it does

get_ui_hierarchy

Returns the current screen as an XML UI hierarchy

take_screenshot

Captures the screen as a base64-encoded PNG

tap_screen

Sends a tap gesture at pixel coordinates

swipe_screen

Sends a swipe gesture between two points over a given duration

type_text

Types text into the focused input field

press_key

Sends an Android keycode event (Back, Home, Enter, etc.)

launch_app

Launches an app by its package/activity component name

execute_adb_command

Runs an arbitrary ADB or ADB shell command

list_devices

Lists all Android devices currently visible to ADB with their serial, state, and model

snapshot_ui

Takes a lightweight UI snapshot and returns a token for use with detect_ui_change

detect_ui_change

Polls for a UI change after an action; accepts a snapshot token as baseline; returns hierarchy only when requested

get_screen_elements

Parses the UI hierarchy and returns structured elements with coordinates and interaction properties; supports tappable, interactive, input, and all modes

get_screen_text

Returns all visible text on screen sorted top-to-bottom, as plain text

check_device_capabilities

Returns structured device information — identity, security posture, and hardware specs — in a single call; supports identity, security, hardware, and all modes

Extra tool packs

Optional packs extend the core toolset. Enable them by setting ADB_EXTRA_TOOL_PACKS in your MCP client config. See docs/extra-tool-packs.md.

app_manager

Package management, app lifecycle control, APK extraction, permission management, and intent injection.

Tool

What it does

list_packages

Lists installed packages with optional filtering, search, and detail levels

get_app_info

Returns full static metadata for a single installed app

install_app

Installs an APK from a host path onto the device

uninstall_app

Removes an installed app by package name

pull_apk

Extracts the installed APK from the device to the host

manage_permission

Grants, revokes, checks, or lists runtime permissions for an app

launch_app_extra

Launches an app by package name, auto-resolving the launcher activity

manage_app

Controls app runtime state — stop, clear data, clear cache, enable, disable

inject_intent

Fires an intent at a component via am start, am broadcast, or am startservice

Full parameter reference: docs/tools.md

Configuration

Configure the server entirely from your MCP client's env block. No files to edit. The env block in the Quick Start above covers the most common settings. For the full reference including security filtering, tool visibility, and timeouts, see docs/configuration.md.

To use a YAML config file instead, set ADB_CONFIG_SOURCE=yaml. See docs/configuration.md for details.

Session recording is separate. Enable it with MCP_LOG_ENABLED=true and MCP_LOG_DIR. Full reference: docs/logging.md.

Documentation

File

Description

docs/setup.md

Prerequisites, installation, and MCP client configuration

docs/tools.md

Full parameter reference for all tools

docs/configuration.md

Reference for environment variables and adb_config.yaml

docs/logging.md

Session recorder — log files, levels, retention, and activation

docs/extra-tool-packs.md

Extra tool packs — enabling packs, the pack contract, and writing your own

docs/troubleshooting.md

Common setup issues and ADB problems

docs/workflows.md

Common multi-tool workflows with examples

CHANGELOG.md

Release history and version changes

Contributing

Contributions are welcome. See CONTRIBUTING.md for guidelines on setup, code standards, and submitting pull requests.

To report a security vulnerability, follow the process in SECURITY.md — do not open a public issue.

Available Tools

11 tools
detect_ui_changeA

Polls the UI hierarchy after an action and returns when the screen content changes or the timeout is reached. Returns changed status and elapsed time. By default, omits the XML hierarchy for efficiency — set return_hierarchy=True to receive the full hierarchy.

For efficient change detection: call snapshot_ui before the action, perform the action, then call detect_ui_change with baseline_token. Only use without baseline_token when you need to wait for a slow transition (loading screens, animations). Do not use to read the current screen state — use get_ui_hierarchy for that.

Inputs: timeout_seconds, baseline_token, return_hierarchy, device_serial. Returns: changed, hierarchy, elapsed_seconds

execute_adb_commandB

The output of an ADB command. Parsed safely via shlex and never passed to a system shell.

Inputs: command (required), use_shell, device_serial. Returns: result

get_ui_hierarchyA

Returns the current Android screen as an XML UI hierarchy.

Use this when you need to locate element coordinates, read text, or find resource IDs to interact with. Do not call this after every action — only call it when you actually need to read screen content. To check if the screen changed after an action, use snapshot_ui before the action and detect_ui_change after.

Inputs: device_serial. Returns: result

launch_appA

An Android app launched by its component name (package/activity).

Inputs: component (required), device_serial. Returns: result

list_devicesA

All Android devices currently visible to ADB, with their serial numbers, connection state, and model names.

Inputs: no named parameters. Returns: result

press_keyA

A key event sent to the Android device using the given keycode integer.

Inputs: keycode (required), device_serial. Returns: result

snapshot_uiA

Takes a lightweight snapshot of the current UI state and returns a short token.

Use this before performing an action (tap, swipe, launch, key press) when you only need to confirm the screen changed afterward — not read its content. Pass the returned token to detect_ui_change as baseline_token. This avoids loading the full XML hierarchy into context unnecessarily. Do not use this when you need to read or interact with screen elements — use get_ui_hierarchy for that.

Inputs: device_serial. Returns: result

swipe_screenB

A swipe gesture on the Android screen from (x1,y1) to (x2,y2) over the given duration.

Inputs: x1 (required), y1 (required), x2 (required), y2 (required), +2 more. Returns: result

take_screenshotB

A PNG screenshot of the current Android device screen with width, height, and base64-encoded image data.

Inputs: device_serial. Returns: image, width, format, height

tap_screenA

A tap gesture at the given pixel coordinates on the Android screen.

Inputs: x (required), y (required), device_serial. Returns: result

type_textA

Text input into the currently focused Android input field.

Spaces are encoded automatically.

Inputs: text (required), device_serial. Returns: result

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 11 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose with no overlap: detect_ui_change monitors for changes, get_ui_hierarchy reads screen content, snapshot_ui captures state tokens, and actions like tap_screen, swipe_screen, type_text, press_key, launch_app, take_screenshot, list_devices, and execute_adb_command each handle specific interactions. Descriptions explicitly differentiate usage scenarios, preventing misselection.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case (e.g., detect_ui_change, get_ui_hierarchy, tap_screen). This uniformity makes the set predictable and easy to understand, with no deviations in style or convention.

    Tool Count5/5

    With 11 tools, this server is well-scoped for Android device automation, covering essential actions like UI interaction, navigation, input, and device management. Each tool serves a clear role without redundancy, making the count appropriate for the domain.

    Completeness5/5

    The toolset provides complete coverage for Android automation: UI reading (get_ui_hierarchy), change detection (detect_ui_change, snapshot_ui), interactions (tap_screen, swipe_screen, type_text, press_key), app control (launch_app), device management (list_devices, execute_adb_command), and visual feedback (take_screenshot). No obvious gaps exist for core workflows.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      F
      maintenance
      A TypeScript-based bridge between AI models and Android device functionality, enabling interaction with Android devices through ADB commands for tasks like app installation, file transfer, UI analysis, and shell command execution.
      10
      444 npm
      56
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      MCP server that gives AI agents full vision and control over Android devices via ADB and scrcpy. Supports screenshots, input, apps, UI automation, shell, files, and clipboard.
      38
      392 npm
      136
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      An MCP server that allows AI agents to drive real Android devices via adb, capturing screenshots, reading the live UI tree, and performing actions like tap, swipe, and type.
      13
      5 npm
      1
      Apache 2.0