uiautomator2-mcp 0.1.0

MCP server for Android device automation via uiautomator2

uiautomator2-mcp

MCP (Model Context Protocol) server for Android device automation via uiautomator2.

Enables AI agents (Claude, etc.) to control Android devices — tap, swipe, type text, take screenshots, manage apps, and more.

Prerequisites

• Python 3.10+
• uv (recommended) or pip
• Android device with USB debugging enabled (or an emulator)
• ADB installed and device visible via adb devices

Quick Start

Claude Code — one command to add & auto-run:

claude mcp add uiautomator2 -- uvx uiautomator2-mcp

That's it. Claude will auto-launch the server when needed.

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "uiautomator2": {
      "command": "uvx",
      "args": ["uiautomator2-mcp"]
    }
  }
}

Before PyPI publish — install from git

# Claude Code
claude mcp add uiautomator2 -- uvx --from "git+https://github.com/stayer147/uiautomator2mcp" uiautomator2-mcp

# Claude Desktop — use in config:
{
  "command": "uvx",
  "args": ["--from", "git+https://github.com/stayer147/uiautomator2mcp", "uiautomator2-mcp"]
}

Alternative methods

# Using pipx
pipx run uiautomator2-mcp

# Using pip (global install)
pip install uiautomator2-mcp
uiautomator2-mcp

# Using python -m
pip install uiautomator2-mcp
python -m uiautomator2_mcp

# From source
git clone https://github.com/stayer147/uiautomator2mcp.git
cd uiautomator2mcp
pip install -e .
uiautomator2-mcp

Available Tools (45)

Connection

Tool	Description
list_devices	List devices visible to ADB and whether they are connected in the MCP session
list_avds	List configured Android Virtual Devices
start_emulator	Start an Android emulator in the background
connect	Connect to a device by serial/IP or auto-detect
disconnect	Disconnect one connected device from the MCP session
device_info	Get device model, screen size, Android version

UI Interaction

Tool	Description
tap	Tap at screen coordinates
multi_tap	Tap the same coordinates multiple times
double_tap	Double-tap at coordinates
long_tap	Long-press at coordinates
swipe	Swipe between two points
drag	Drag between two points
input_text	Type text into the focused field
press_key	Press a device key (home, back, enter, etc.)

Compound Actions

Tool	Description
tap_and_wait	Tap an element, wait for the next UI state, and return a fresh hierarchy snapshot
tap_sequence	Execute a validated sequence of taps, waits, typing, key presses, and swipes

Element Operations

Tool	Description
find_element	Find element by text, resource ID, class, description, or XPath
tap_element	Find and tap an element
double_tap_element	Find and double-tap an element by selector or XPath
set_element_text	Set text in an input field
element_exists	Check if an element exists
wait_element	Wait for an element to appear

Screenshots & UI Hierarchy

Tool	Description
screenshot	Take a screenshot as a saved file or inline JSON/base64 image payload
dump_hierarchy	Get XML UI hierarchy or a compact text summary
get_ui_tree	Get a richer JSON UI tree with element state for agent analysis

Agent-friendly analysis outputs

• screenshot(inline=True) returns a JSON object with base64-encoded image data, MIME type, dimensions, and byte size so MCP clients can render the image without opening a filesystem path.
• screenshot(save_path="/tmp/screen.jpg", quality=70, max_width=1280) keeps the original save-to-disk workflow while allowing resize/compression controls.
• get_ui_tree() returns a structured JSON array of UI elements with text, resource_id, class_name, content_desc, bounds, clickable, enabled, focused, selected, checked, scrollable, and index.
• dump_hierarchy(compact=True) remains available as the lightweight one-line-per-element snapshot, while dump_hierarchy(compact=False) still returns raw XML.

App Management

Tool	Description
app_start	Launch an app
app_stop	Force-stop an app
app_install	Install an APK
app_uninstall	Uninstall an app
app_clear	Clear app data
app_info	Get app information
app_list_running	List running apps
current_app	Get current foreground app

Device Control

Tool	Description
screen_on	Wake up the device
screen_off	Turn off the screen
unlock	Unlock the device
open_notification	Open notification panel
open_quick_settings	Open quick settings
get_clipboard	Get clipboard content
set_clipboard	Set clipboard content

Diagnostics

Tool	Description
clear_logs	Clear logcat buffers on the device
get_logs	Read filtered logcat output by package, level, timestamp, and line count

Shell & Files

Tool	Description
shell	Run a shell command on the device
push_file	Push a file to the device
pull_file	Pull a file from the device

Example Workflow

When only one device is connected in the MCP session, tools can omit device_id. If you connect multiple devices, pass device_id explicitly. Multi-device targeting is now supported consistently across the interactive UI, app-management, device-control, watcher, clipboard, and file-transfer tools, in addition to diagnostics tools like clear_logs and get_logs.

1. List available devices: list_devices()
2. Connect to one device: connect("emulator-5554")
3. Optionally connect a second device: connect("emulator-5556")
4. Inspect a specific device: device_info(device_id="emulator-5554")
5. Take a screenshot to see the current screen: screenshot(device_id="emulator-5554") or request inline JSON/base64 output with screenshot(inline=True, max_width=1080, device_id="emulator-5554")
6. Dump hierarchy to understand the lightweight UI structure: dump_hierarchy(device_id="emulator-5554")
7. Get a richer UI tree when state matters: get_ui_tree(device_id="emulator-5554")
8. Tap elements by text or resource ID
9. Double-tap directly via XPath when needed, e.g. double_tap_element(xpath="//android.widget.TextView[@text='Gallery']")
10. Type text into input fields
11. Take another screenshot to verify results

Example bug-report workflow

1. Clear old logs: clear_logs()
2. Reproduce the bug using the UI interaction tools
3. Capture error logs: get_logs(level="E", package="com.example.app")
4. Take a screenshot of the failing state, optionally inline for vision analysis
5. Dump hierarchy for a lightweight snapshot or get_ui_tree() for richer element state

Example login in one tool call

tap_sequence(
  steps=[
    {"action": "tap_element", "resource_id": "com.example:id/email"},
    {"action": "input_text", "text": "[e-mail]"},
    {"action": "tap_element", "resource_id": "com.example:id/password"},
    {"action": "input_text", "text": "correct horse battery staple"},
    {"action": "tap_element", "resource_id": "com.example:id/sign_in"},
    {"action": "wait", "resource_id": "com.example:id/home_feed", "timeout": 15}
  ]
)

Publishing to PyPI

uv build
uv publish

After publishing, uvx uiautomator2-mcp will work out of the box.

License

MIT