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

Related MCP server: DeepADB

✨ 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

• 📦 Standalone Executable - Bundle into a standalone app with PyInstaller or Nuitka — no Python runtime required

• 🧰 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

• ⚙️ Config Files - TOML/YAML/JSON config with auto-discovery

• 🔒 Clean Code - Type hints, linted, formatted — easy to extend

🎯 Use Cases

🏗️ 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 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 with pip
python -m pip install uiautomator2-mcp-server

After installation, the short alias u2mcp is available:

u2mcp stdio

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

Building a Standalone Executable

You can bundle the server into a standalone application — no Python installation required on the target machine.

PyInstaller (Recommended)

Fast build, no C compiler required.

# 1. Install PyInstaller
uv sync --group pyinstaller

# 2. Build
pyinstaller u2mcp.spec

This produces a dist/u2mcp/ directory containing the executable and all runtime files. Distribute the entire folder as a portable application.

Nuitka

Compiles Python to C, producing native .so/.pyd/.dll binaries — provides a basic level of source code protection. Requires a C/C++ compiler (MSVC on Windows, GCC/Clang on Linux/macOS).

Build options are pre-configured in main.py via Nuitka project directives:

# 1. Install Nuitka
uv sync --group nuitka

# 2. Build
nuitka main.py

Running the Bundled Server

Regardless of which tool you used:

# STDIO mode (for local MCP clients)
u2mcp stdio

# HTTP mode (for remote access)
u2mcp http -H 0.0.0.0 -p 8000

Note: The output bundles the Python runtime and all Python dependencies, so the target machine does not need Python, pip, or uv installed. However, adb must still be available on the system PATH (or set via the ADBUTILS_ADB_PATH environment variable).

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 --no-auth

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

# 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).

Configuration Files

You can configure u2mcp using config files instead of (or in addition to) CLI flags. Supported formats: TOML, YAML, and JSON.

Config File Locations

The server automatically discovers config files in platform-specific directories:

In each directory, the server looks for the first matching file: u2mcp.toml, u2mcp.yaml, u2mcp.yml, u2mcp.json (at most one file per directory).

Priority order: CLI args > Environment variables > Config file (cwd > user > system) > Defaults.

Using a Custom Config File

# Via CLI option
u2mcp stdio --config-file my-config.toml

# Via environment variable
U2MCP_CONFIG_FILE=my-config.toml u2mcp stdio

Config File Structure

Config files use command names as top-level keys:

# u2mcp.toml
[stdio]
log-level = "debug"
check-adb = false
include-tags = "device:*,action:touch"

[http]
host = "0.0.0.0"
port = 8000
auth = true
json-response = true

# u2mcp.yaml
stdio:
  log-level: debug
  check-adb: false

http:
  host: "0.0.0.0"
  port: 8000
  auth: false

{
  "stdio": {
    "log-level": "warning",
    "print-tags": false
  }
}

Environment Variables

CLI parameters can be set via environment variables with the U2MCP_{COMMAND}_{PARAM} format:

U2MCP_STDIO_LOG_LEVEL=debug u2mcp stdio
U2MCP_HTTP_HOST=0.0.0.0 U2MCP_HTTP_PORT=9000 u2mcp http
U2MCP_HTTP_AUTH=false u2mcp http

Example Config Files

See the examples/ directory for ready-to-use config files:

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.

1. Connect your Android device via USB with USB debugging enabled

2. Configure your MCP client to use this server (see MCP Client Configuration)

3. Initialize the device (required first time):

   "Initialize my Android device"

4. 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-auth - Disable authentication (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:

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.

1. Open Postman and create a new MCP Request

2. 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)

3. Click Load Capabilities to connect and discover available tools

4. Use the Tools, Resources, and Prompts tabs to interact with the server

5. 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.

1. Open Cursor Settings (Cmd/Ctrl + ,)

2. Navigate to MCP Servers

3. 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.

1. Download and install Cherry Studio

2. Open Settings and navigate to MCP Servers

3. 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-auth

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).

1. Download and install ChatMCP

2. Open Settings and navigate to MCP Servers

3. 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-auth

Then in ChatMCP, select HTTP mode and enter:

URL: http://localhost:8000/mcp

Cline

Cline is an AI coding assistant extension that supports MCP.

1. Open Cline settings in your IDE

2. Navigate to MCP Servers section

3. Add the server configuration:

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

Continue

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

1. Install the Continue extension

2. Open Continue settings

3. 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-auth

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:

1. Educational Example: Demonstrates best practices for MCP skill development

2. 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

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:

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