android-device-mcp-server

An MCP (Model Context Protocol) server that gives Claude full observation and control of a connected Android device via ADB.

Installation

# Recommended: run ephemerally with uvx (no install needed)
uvx android-device-mcp-server

# Or install with pip
pip install android-device-mcp-server
android-device-mcp-server

Add to a project

In .mcp.json (or Claude Code's MCP config):

{
  "mcpServers": {
    "android-device": {
      "command": "uvx",
      "args": ["android-device-mcp-server"]
    }
  }
}

Prerequisites

• Python 3.12+
• adb on PATH (brew install android-platform-tools or from Android SDK)
• At least one connected device or running emulator (adb devices to verify)

Tools

Observation

capture_screen is the primary tool. It returns both a compressed JPEG screenshot and the UI hierarchy in a compact text format in a single call, giving Claude visual context and structured element data together.

The compact UI format looks like:

0 FrameLayout @540,1200
1 Button "Pay Now" #pay_btn @540,550 [C]
2 View (Payments) @405,2300 [C]
3 ScrollView @540,1300 [S]

Flags: [C]=clickable, [LC]=long-clickable, [S]=scrollable, [*]=selected, [F]=focused, [v]=checked, [?]=checkable, [D]=disabled, [P]=password

Actions

Prefer tap_element over tap — it finds the element by text, content-description, or resource-id and computes the tap coordinates automatically. It also supports partial text matching as a fallback (e.g., "Pay" matches "Pay Now").

Supported keys for press_key: back, home, enter, tab, delete, volume_up, volume_down, power, menu, search, dpad_up, dpad_down, dpad_left, dpad_right, dpad_center, space, escape, wakeup.

App Lifecycle

Utility

Configuration

All settings can be overridden via environment variables:

Invalid values are logged and silently replaced with defaults.

How the UI hierarchy works

adb shell uiautomator dump produces an XML tree of every visible UI element with its text, content-description, bounds, and interaction flags. This server parses that XML and returns a compact text format optimized for LLM consumption — reducing token usage by ~80% compared to raw XML while preserving all the information Claude needs to reason about and interact with the UI.

For Compose-based apps, class names are generic (android.view.View instead of Button, TextField, etc.), but text, content-description, bounds, and clickability are all present — which is everything needed.