uiautomator2-mcp-server

🇨🇳 中文说明

Code of Conduct: Please follow our Code of Conduct when participating in this project.

An MCP server that provides tools for controlling Android devices using uiautomator2.

Use AI to automate your Android device: take screenshots, tap/swipe, manage apps, send text, and more.

📺 Demo

Conversational Android Automation

User says: "Search cat videos on xxx App then play the video and swap to the next video"

AI automatically:

✅ Launch app → Tap search → Enter keywords → Execute search → Tap result -> Swap to next video

Control Android devices with natural language, no coding required

Detailed example: .skills/douyin-search

✨ Features

📱 Multi-Device - One server, many phones
🔍 XPath Filtering - Dump only the UI elements you need — save tokens and speed up responses
🎛️ Tool Filtering - Show the AI only the tools it needs — fewer hallucinations, better results
⚡ Zero Setup - Run with uvx immediately, no installation needed
🧰 70+ Tools - Click, swipe, type, apps, screenshots — everything you need
🧪 Built-in Testing - Includes AI-driven UI test framework out of the box
🔄 Two Modes - STDIO for local, HTTP for remote
🔒 Clean Code - Type hints, linted, formatted — easy to extend

🎯 Use Cases

Scenario	Description
🧪 Automated Testing	Run natural language UI tests with AI-driven test framework
⚡ Rapid Prototyping	Quickly test Android app interactions without writing code
♿ Accessibility Testing	Verify app accessibility features automatically
📊 Health Monitoring	Periodic device health and status checks
🤖 Task Automation	Automate repetitive tasks like form filling, navigation
🔬 Remote Debugging	Inspect UI hierarchy and capture screenshots remotely

🏗️ Architecture

graph TD
    AI[AI Assistant<br/>Claude/GPT/etc.] --> MCP[MCP Protocol]
    MCP --> Server[u2mcp Server]
    Server --> uiautomator2[uiautomator2]
    uiautomator2 --> ADB[ADB]
    ADB --> Device[Android Device<br/>Physical/Emulator]

    style AI fill:#e1f5ff
    style MCP fill:#fff4e6
    style Server fill:#f3e5f5
    style uiautomator2 fill:#e8f5e9
    style ADB fill:#fff3e0
    style Device fill:#fce4ec

Migration from v0.1.x

If you're upgrading from v0.1.3 or earlier: The CLI now requires an explicit subcommand. Change your command from:

# Old (v0.1.3 and earlier)
u2mcp

to:

# New (v0.2.0+)
u2mcp stdio

All other commands remain the same (just add the transport subcommand).

Prerequisites

Python 3.11+
adb in your PATH (install via Android SDK Platform Tools)
Android device with USB debugging enabled

💡 Tool Selection Recommendation:

MCP Client Usage (Claude Desktop, Cursor, etc.): uv is recommended for direct package execution with uvx

Standalone/Debugging: You can use uv, pip, or pipx

For most use cases, installing uv is sufficient.

Installing Enhanced Python Package Managers

The following are two optional enhanced package managers. You can choose to install one of them, or skip this step if you prefer.

Installing uv (Recommended | Optional)

Most MCP clients (like Claude Desktop) use uvx to run Python MCP servers. uvx is part of the uv toolkit.

Why choose uvx? uvx can run Python packages directly from PyPI without manual installation - just use uvx package-name and it handles the rest. This makes it perfect for MCP client configurations.

macOS / Linux:
```
curl -LsSf https://astral.sh/uv/install.sh | sh
```
Windows (PowerShell):
```
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```
Or use winget:
```
winget install --id=astral-sh.uv -e
```
Verify installation:
```
uv --version
uvx --version
```
Installing pipx (Optional)

pipx is another tool for installing and running Python CLI applications in isolated environments.

pipx vs uvx: Like uvx, pipx can also run packages directly with pipx run package-name. However, uvx is generally faster and is more commonly used in the MCP ecosystem.

macOS / Linux:
```
python3 -m pip install --user pipx
python3 -m pipx ensurepath
```
Windows:
```
python -m pip install --user pipx
python -m pipx ensurepath
```

Installation

Preferred: Run directly without installation using uvx (recommended) or pipx run from PyPI:

# Run directly with uvx (recommended)
uvx uiautomator2-mcp-server stdio

# Or use the shorter alias (v0.3.0+)
uvx u2mcp stdio

# Or run directly with pipx
pipx run uiautomator2-mcp-server stdio

If you need global installation for long-term use, you can also choose to install:

# Install using uv (tool method)
uv tool install uiautomator2-mcp-server

# Or install with pipx
pipx install uiautomator2-mcp-server

# Or install the u2mcp alias (v0.3.0+)
pip install u2mcp

If you don't want to use uv, pipx or other third-party package managers, you can directly use Python's default package manager pip to install this software:

python -m pip install uiautomator2-mcp-server

Note on Package Name:
While the CLI command is u2mcp, the PyPI package name is uiautomator2-mcp-server. We plan to simplify this to u2mcp in v1.0.0. For now, please install using the full package name above.

ℹ️ Note:
pip does not support running without installation

Running Modes

Note: The commands below use u2mcp, which requires the package to be installed. If you haven't installed it yet, you can run directly using uvx uiautomator2-mcp-server ... instead.

The MCP server can run in two modes:

STDIO Mode (for local MCP clients)

# If installed
u2mcp stdio

# Or run directly without installation
uvx uiautomator2-mcp-server stdio

This mode communicates via standard input/output and is typically used by MCP clients that spawn the server process directly.

HTTP Mode (for remote/network access)

# If installed
u2mcp http -H 0.0.0.0 -p 8000 -n

# Or run directly without installation
uvx uiautomator2-mcp-server http -H 0.0.0.0 -p 8000 -n

# With authentication token (if installed)
u2mcp http -H 0.0.0.0 -p 8000 -t YOUR_SECRET_TOKEN

# Or run directly without installation
uvx uiautomator2-mcp-server http -H 0.0.0.0 -p 8000 -t YOUR_SECRET_TOKEN

The server will listen on http://localhost:8000/mcp (or your specified host/port).

CLI Utility Commands

Note: The commands below use u2mcp, which requires the package to be installed. If you haven't installed it yet, you can run directly using uvx uiautomator2-mcp-server ... instead.

The u2mcp CLI provides several utility commands for exploring available tools and tags:

# List all available tools
u2mcp tools

# Or run directly
uvx uiautomator2-mcp-server tools

# Show detailed information about a specific tool
u2mcp info screenshot

# Show tools matching a pattern (supports wildcards)
u2mcp info "device:*"     # All device tools
u2mcp info "*screenshot*" # Tools with 'screenshot' in name

# List all available tool tags
u2mcp tags

# Show version information
u2mcp --version

Tool Filtering

Note: The commands below use u2mcp, which requires the package to be installed. Replace with uvx uiautomator2-mcp-server ... if running directly.

You can selectively expose tools using tag-based filtering. This reduces the number of tools available to the LLM, which can improve performance and reduce confusion.

# Only expose device management tools
u2mcp stdio -i device:manage

# Or run directly
uvx uiautomator2-mcp-server stdio -i device:manage

# Only expose touch and gesture operations
u2mcp stdio -i action:touch,action:gesture

# Exclude screen mirroring tools
u2mcp stdio -e screen:mirror

# Only expose app lifecycle and element interaction tools
u2mcp stdio -i app:lifecycle,element:interact

# Exclude shell command tools (for security)
u2mcp stdio -e device:shell

# Only expose input-related tools
u2mcp stdio -i input:text,input:keyboard

# Combine include and exclude
u2mcp stdio -i device:info,action:touch -e screen:capture

# Wildcard patterns - include all device tools
u2mcp stdio -i "device:*"

# Wildcard patterns - include all touch and gesture tools
u2mcp stdio -i "action:to*"

# Wildcard patterns - exclude all screen tools
u2mcp stdio -e "screen:*"

# Wildcard patterns - exclude all mirror tools (screen:mirror, etc.)
u2mcp stdio -e "*:mirror"

# List all available tags
u2mcp tags

Quick Start

Before you start: Make sure you have configured an MCP client (like Claude Desktop) to use this server. See MCP Client Configuration below for details.

Connect your Android device via USB with USB debugging enabled
Configure your MCP client to use this server (see MCP Client Configuration)
Initialize the device (required first time):

"Initialize my Android device"
Start automating:

"Take a screenshot" "Tap at coordinates 500, 1000" "Swipe up" "Open YouTube app"

Short Options:

All common options support short flags for convenience:

-l / --log-level - Set log level
-i / --include-tags - Include tools by tags
-e / --exclude-tags - Exclude tools by tags
-H / --host - Set host address (HTTP mode)
-p / --port - Set port number (HTTP mode)
-t / --token - Set authentication token (HTTP mode)
-n / --no-token - Disable token verification (HTTP mode)

Wildcard Support:

The --include-tags and --exclude-tags options support wildcard patterns:

* matches any characters
? matches exactly one character
device:* matches all device:* tags
*:mirror matches all mirror tags (screen:mirror, etc.)
action:to* matches action:touch, action:tool (if exists)

Available Tags:

Tag	Description
`device:manage`	Device connection, initialization, and management
`device:info`	Device information and status
`device:capture`	Screenshots and UI hierarchy
`device:shell`	Shell command execution
`action:touch`	Click and tap actions
`action:gesture`	Swipe and drag gestures
`action:key`	Physical key presses
`action:screen`	Screen control (on/off)
`app:manage`	Install and uninstall apps
`app:lifecycle`	Start and stop apps
`app:info`	App information and listing
`app:config`	App configuration (clear data, permissions)
`element:wait`	Wait for elements/activities
`element:interact`	Click and interact with elements
`element:query`	Get element info (text, bounds)
`element:modify`	Modify element (set text)
`element:gesture`	Element-specific gestures (swipe, scroll)
`element:capture`	Element screenshots
`input:text`	Text input and clearing
`input:keyboard`	Keyboard control
`clipboard:read`	Read clipboard
`clipboard:write`	Write clipboard
`screen:mirror`	Screen mirroring (scrcpy)
`screen:capture`	Screen screenshots
`util:delay`	Delay/sleep utility

Testing and Debugging

Using MCP Inspector

MCP Inspector is a command-line tool for testing and debugging MCP servers without requiring an AI client.

# Install MCP Inspector
npm install -g @modelcontextprotocol/inspector

# Inspect the server in STDIO mode
npx @modelcontextprotocol/inspector u2mcp stdio

# Or inspect the server in HTTP mode
# First start the server: u2mcp http --host 0.0.0.0 --port 8000
# Then run inspector with the URL
npx @modelcontextprotocol/inspector http://localhost:8000/mcp

The inspector will display:

Available tools and their parameters
Server resources and prompts
Real-time tool execution results
Request/response logs

Using Postman

Postman has native MCP support for testing and debugging MCP servers.

Open Postman and create a new MCP Request
Enter the server connection details:

STDIO Mode:

Command: u2mcp
Arguments: stdio

HTTP Mode:

URL: http://localhost:8000/mcp

(First start the server: u2mcp http --host 0.0.0.0 --port 8000)

Click Load Capabilities to connect and discover available tools
Use the Tools, Resources, and Prompts tabs to interact with the server
Click Run to execute tool calls and view responses

For more information, see the Postman MCP documentation.

Using cURL

You can also test the HTTP endpoint using cURL with JSON-RPC 2.0 requests:

# 1. Start the server first
u2mcp http --host 0.0.0.0 --port 8000

# 2. In another terminal, send MCP requests
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

# Call a tool (e.g., list devices)
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "device_list",
      "arguments": {}
    }
  }'

MCP Client Configuration

This MCP server can be used with any MCP-compatible client. Below are configuration instructions for popular clients.

Claude Desktop

Add to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

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

If you installed the package globally, you can also use:

{
  "mcpServers": {
    "android": {
      "command": "u2mcp",
      "args": ["stdio"]
    }
  }
}

Cursor

Cursor is an AI-powered code editor with native MCP support.

Open Cursor Settings (Cmd/Ctrl + ,)
Navigate to MCP Servers
Add a new server:

{
  "mcpServers": {
    "android": {
      "command": "u2mcp",
      "args": ["stdio"]
    }
  }
}

Cherry Studio

Cherry Studio is a cross-platform AI desktop client with full MCP support. Ideal for Android device automation tasks.

Download and install Cherry Studio
Open Settings and navigate to MCP Servers
Click Add Server and configure:

Option A: Using uvx (recommended)

Command: uvx
Arguments: uiautomator2-mcp-server stdio

Option B: Using installed u2mcp command

Command: u2mcp
Arguments: stdio

Option C: HTTP Mode First start the server:

u2mcp http --host 0.0.0.0 --port 8000 --no-token

Then in Cherry Studio, select HTTP mode and enter:

URL: http://localhost:8000/mcp

For detailed MCP configuration in Cherry Studio, see the official documentation.

ChatMCP

ChatMCP is an open-source AI chat client implementing the MCP protocol. Supports multiple LLM providers (OpenAI, Claude, Ollama).

Download and install ChatMCP
Open Settings and navigate to MCP Servers
Add a new server:

Using uvx (recommended)

Command: uvx
Arguments: uiautomator2-mcp-server stdio

Using installed u2mcp command

Command: u2mcp
Arguments: stdio

HTTP Mode First start the server:

u2mcp http --host 0.0.0.0 --port 8000 --no-token

Then in ChatMCP, select HTTP mode and enter:

URL: http://localhost:8000/mcp

Cline

Cline is an AI coding assistant extension that supports MCP.

Open Cline settings in your IDE
Navigate to MCP Servers section
Add the server configuration:

{
  "android": {
    "command": "u2mcp",
      "args": ["stdio"]
  }
}

Continue

Continue is an AI pair programmer extension for VS Code and JetBrains.

Install the Continue extension
Open Continue settings
Add to your MCP servers configuration:

{
  "mcpServers": {
    "android": {
      "command": "u2mcp",
      "args": ["stdio"]
    }
  }
}

HTTP Mode Configuration

For clients that support HTTP connections (or for remote access), start the server first:

u2mcp http --host 0.0.0.0 --port 8000 --no-token

Then configure your client to connect to http://localhost:8000/mcp.

Note: Check your client's documentation for HTTP MCP server configuration, as the setup varies by client.

Other MCP Clients

The server follows the Model Context Protocol specification and can be used with any MCP-compatible client, including:

Windsurf - Development environment with MCP support
Zed - Code editor with MCP capabilities
LibreChat - Chat interface supporting MCP
Chainlit - Platform for building AI applications

Refer to your client's documentation for specific configuration details.

AI-Driven UI Testing

Prerequisite: To use AI-driven UI testing, you must first configure an MCP client (such as Claude Desktop, Cursor, or Cherry Studio) to connect to this server. See the MCP Client Configuration section above for setup instructions.

This project includes an AI-driven UI testing framework using the .skills/ system. The android-ui-test skill serves a dual purpose:

Educational Example: Demonstrates best practices for MCP skill development
Production Testing: Acts as the project's automated UI test suite for CI/CD

Skill Structure

.skills/android-ui-test/
├── SKILL.md                     # Core skill definition (YAML metadata + lightweight description)
├── README.md                    # Architecture overview and quick start
├── examples/                    # Learning materials
│   └── usage-examples.md        # Detailed usage patterns and examples
└── references/                  # Technical specifications
    └── test-specification.md    # Complete test specification (TC001-TC010)

Running UI Tests

Simply ask the AI to execute the UI test:

Run the Android UI test suite on my connected device

The AI will:

Auto-detect and connect to the first available device
Run comprehensive tests covering all device operations
Provide a detailed test report with pass/fail/skip status

Test Coverage

Category	Tests
Device	Connection, Info, Screenshot, Hierarchy, Doctor
Touch	Click, Long Click, Double Click
Gesture	Swipe, Drag, Key Press
App	List, Start, Wait, Info, Permissions
Element	Wait, Exists, Bounds, Get Text, Click, Screenshot
Input	Text Input, Focused Text, Keyboard
Clipboard	Read/Write (with known limitations)

Sample Test Report

Android UI Test Summary
=======================

Device: UGAILFCIU88TT469 (PDKM00, Android 11, SDK 31)

Test Cases:
  [PASS] TC001: Device Connection & Initialization
  [PASS] TC002: Device Info & Capture
  [PASS] TC003: Touch Actions
  [PASS] TC004: Gesture Actions
  [PASS] TC005: Application Management
  [PASS] TC006: Element Operations
  [PASS] TC007: Input & Keyboard
  [SKIP] TC008: Clipboard Operations (Android security restriction)

Total: 7 passed, 1 skipped, 0 failed

Creating Custom Skills

See .skills/android-ui-test/ for a complete reference implementation.

Each skill directory contains:

SKILL.md - YAML frontmatter with metadata and lightweight description
examples/ - Detailed usage patterns for learning
references/ - Technical specifications and test cases

Available Tools

The server provides 70+ tools organized into the following categories:

Category	Description
Device	Connection, info, screenshot, hierarchy, shell
Actions	Touch, gestures, key presses, screen control
Apps	Install, launch, manage, list app info
Element	XPath-based element location and interaction (v0.3.0+)
Input	Text input, keyboard control, focused text
Clipboard	Read/write clipboard content
Toast	Android Toast message detection and display
Scrcpy	Screen mirroring with scrcpy

Listing Tools

Run these commands to explore available tools:

# List all tools
u2mcp tools

# Show detailed info for a specific tool
u2mcp info screenshot

# Show tools matching a pattern (supports wildcards)
u2mcp info "device:*"     # All device tools
u2mcp info "*screenshot*" # Tools with 'screenshot' in name
u2mcp info "xpath:*"      # All XPath tools (v0.3.0+)

# List all tool tags
u2mcp tags

Key Features

XPath-based element interaction - Primary method for UI automation, LLM-optimized (v0.3.0+)
Tag-based filtering - Expose only relevant tools to reduce AI confusion
Comprehensive coverage - Everything from basic clicks to advanced element queries

Example Usage

You: Take a screenshot
Claude: [Uses screenshot tool, displays image]

You: What apps are installed?
Claude: [Lists installed apps using app_list]

You: Open the YouTube app
Claude: [Uses app_start with package name]

You: Search for "cats"
Claude: [Uses click to tap search bar, then send_text to type "cats"]

You: Scroll down
Claude: [Uses swipe to scroll down]

License

Apache-2.0

Name		Name	Last commit message	Last commit date
Latest commit History 196 Commits
.claude		.claude
.github		.github
.skills		.skills
assets		assets
src/u2mcp		src/u2mcp
tests		tests
.coveragerc		.coveragerc
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
.mypy.ini		.mypy.ini
.pre-commit-config.yaml		.pre-commit-config.yaml
.readthedocs.yaml		.readthedocs.yaml
.ruff.toml		.ruff.toml
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
README.md		README.md
README.zh-CN.md		README.zh-CN.md
pyproject.toml		pyproject.toml
pytest.ini		pytest.ini
server.json		server.json
server.py		server.py

Folders and files

Latest commit

History

Repository files navigation

uiautomator2-mcp-server

📺 Demo

Conversational Android Automation

✨ Features

🎯 Use Cases

🏗️ Architecture

Migration from v0.1.x

Prerequisites

Installing Enhanced Python Package Managers

Installation

Running Modes

STDIO Mode (for local MCP clients)

HTTP Mode (for remote/network access)

CLI Utility Commands

Tool Filtering

Quick Start

Testing and Debugging

Using MCP Inspector

Using Postman

Using cURL

MCP Client Configuration

Claude Desktop

Cursor

Cherry Studio

ChatMCP

Cline

Continue

HTTP Mode Configuration

Other MCP Clients

AI-Driven UI Testing

Skill Structure

Running UI Tests

Test Coverage

Sample Test Report

Creating Custom Skills

Available Tools

Listing Tools

Key Features

Example Usage

License

About

Topics

Resources

License

Code of conduct

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 8

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages