Uiautomator2 Mcp Server

uiautomator2-mcp-server

[](https://pypi.org/project/uiautomator2-mcp-server/)

[](https://github.com/tanbro/uiautomator2-mcp-server/releases) [](https://github.com/tanbro/uiautomator2-mcp-server/actions/workflows/ci.yml) [](https://codecov.io/gh/tanbro/uiautomator2-mcp-server)

[](https://lobehub.com/mcp/tanbro-uiautomator2-mcp-server)

[](README.md) [](README.zh-CN.md)

-----

> - 🇨🇳 [中文说明](README.zh-CN.md)

-----

Code of Conduct: Please follow our [Code of Conduct](CODEOFCONDUCT.md) 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:

[](https://www.bilibili.com/video/BV1wGF4zFEev/) [](assets/douyin-demo-2x.mp4)

• ✅ 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](.skills/douyin-search/SKILL.md)

---

✨ 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

| 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 AssistantClaude/GPT/etc.] --> MCP[MCP Protocol]
    MCP --> Server[u2mcp Server]
    Server --> uiautomator2[uiautomator2]
    uiautomator2 --> ADB[ADB]
    ADB --> Device[Android DevicePhysical/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: ``bash curl -LsSf https://astral.sh/uv/install.sh | sh ``

Windows (PowerShell): ``powershell powershell -c "irm https://astral.sh/uv/install.ps1 | iex" ``

Or use winget: ``powershell winget install --id=astral-sh.uv -e ``

Verify installation: ``bash 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: ``bash python3 -m pip install --user pipx python3 -m pipx ensurepath ``

Windows: ``powershell 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:

| Priority | Location | Platform Example | |----------|----------|-----------------| | 1 (lowest) | System config dir | /etc/u2mcp/ (Linux), C:\ProgramData\u2mcp\ (Windows) | | 2 | User config dir | ~/.config/u2mcp/ (Linux), %APPDATA%\u2mcp\ (Windows) | | 3 (highest) | Current working directory | ./ |

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/](examples/) directory for ready-to-use config files:

| File | Description | |------|-------------| | [config-minimal-stdio.toml](examples/config-minimal-stdio.toml) | Minimal stdio config with quiet mode | | [config-full.toml](examples/config-full.toml) | Full config with stdio, http, and doctor sections | | [config-filtered-tools.toml](examples/config-filtered-tools.toml) | Tool filtering by tags | | [config-http-server.yaml](examples/config-http-server.yaml) | HTTP server config in YAML format | | [config-quiet-mode.json](examples/config-quiet-mode.json) | Quiet mode config in JSON format |

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](#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](#mcp-client-configuration))
3. Initialize the device (required first time):

> "Initialize my Android device"

1. 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:

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

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: tanbro
• Source: tanbro/uiautomator2-mcp-server
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.