# Uiautomator2 Mcp Server

> A MCP (Model Context Protocol) server that provides tools for controlling and interacting with Android devices using uiautomator2.

- **Type:** MCP server
- **Install:** `agentstack add mcp-tanbro-uiautomator2-mcp-server`
- **Verified:** Pending review
- **Seller:** [tanbro](https://agentstack.voostack.com/s/tanbro)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [tanbro](https://github.com/tanbro)
- **Source:** https://github.com/tanbro/uiautomator2-mcp-server

## Install

```sh
agentstack add mcp-tanbro-uiautomator2-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](CODE_OF_CONDUCT.md) when participating in this project.

An [MCP](https://modelcontextprotocol.io/) server that provides tools for controlling Android devices using [uiautomator2](https://github.com/openatx/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

```mermaid
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:

```bash
# Old (v0.1.3 and earlier)
u2mcp
```

to:

```bash
# 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](https://developer.android.com/tools/releases/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:

```bash
# 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:

```bash
# 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:

```bash
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:

```bash
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.

```bash
# 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](https://nuitka.net/user-documentation/user-manual.html#nuitka-project-options):

```bash
# 1. Install Nuitka
uv sync --group nuitka

# 2. Build
nuitka main.py
```

#### Running the Bundled Server

Regardless of which tool you used:

```bash
# 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)

```bash
# 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)

```bash
# 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

```bash
# 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:

```toml
# 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
```

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

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

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

#### Environment Variables

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

```bash
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:

```bash
# 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.

```bash
# 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"

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

| 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](https://github.com/tanbro)
- **Source:** [tanbro/uiautomator2-mcp-server](https://github.com/tanbro/uiautomator2-mcp-server)
- **License:** Apache-2.0

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-tanbro-uiautomator2-mcp-server
- Seller: https://agentstack.voostack.com/s/tanbro
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.