# 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 Assistant
Claude/GPT/etc.] --> MCP[MCP Protocol]
MCP --> Server[u2mcp Server]
Server --> uiautomator2[uiautomator2]
uiautomator2 --> ADB[ADB]
ADB --> Device[Android Device
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:
```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
- Install preβcompiled binary (recommended)οΌ
- macOS / Linux
```bash
curl -fsSL https://raw.githubusercontent.com/tanbro/uiautomator2-mcp-server/main/scripts/install.sh | bash
```
- Windows
```powershell
irm https://raw.githubusercontent.com/tanbro/uiautomator2-mcp-server/main/scripts/install.ps1 | iex
```
After installation, the short alias `u2mcp` is available:
```bash
u2mcp --version
```
Supported platforms for the pre-compiled binaries:
| Platform | Release asset | Requirement |
|----------|---------------|-------------|
| Linux x86_64 | `u2mcp-x86_64-unknown-linux-gnu-.tar.gz` | glibc; built in `quay.io/pypa/manylinux_2_28_x86_64` |
| Linux aarch64 | not published | β |
| macOS (Apple Silicon) | `u2mcp-aarch64-apple-darwin-.tar.gz` | arm64 Mac |
| Windows x64 | `u2mcp-x86_64-pc-windows-msvc-.zip` | x64 Windows (ARM64 runs it under emulation) |
Release assets are named with a Rust-style target triple, so a new ABI is a
new triple rather than a new naming scheme. The Linux floor is the build
image's, not a number we maintain here: the image above is a manylinux profile
whose name states the glibc it targets. musl systems (Alpine and friends),
distributions older than that profile (CentOS 7, Debian 9) and Intel Macs have
no pre-compiled binary and must install from PyPI below.
- 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 --version
```
----
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:info", "action:touch"]
exclude-tools = ["shell_command"]
[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 -i action:gesture
# Exclude screen mirroring tools
u2mcp stdio -e screen:mirror
# Only expose app lifecycle and element interaction tools
u2mcp stdio -i app:lifecycle -i xpath:interact
# Exclude shell command tools (for security)
u2mcp stdio -e device:shell
# Only expose input-related tools
u2mcp stdio -i input:text
# Combine include and exclude
u2mcp stdio -i device:info -i action:touch -e screen:capture
# Bare category tags expose a whole category
u2mcp stdio -i device
# Filter by tool name instead of tags
u2mcp stdio --include-tools click --include-tools screenshot
# 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)
**Filtering Options:**
`--include-tags`/`--exclude-tags` and `--include-tools`/`--exclude-tools` take values as repeatable flags or lists in the config file:
```bash
# Allowlist: only expose touch actions and the screenshot tool
u2mcp stdio --include-tags action:touch --include-tools screenshot
# Denylist: expose everything except shell and mirroring
u2mcp stdio --exclude-tags device:shell --exclude-tags screen:mirror
```
Include filters act as an allowlist (only matching tools are exposed); exclude filters remove from that set afterwards and take precedence. Within a direction, tag and tool filters combine as a union.
Each tool carries two tags: a bare category (e.g. `device`) and a subcategory (e.g. `device:capture`). Selecting a bare tag exposes the whole category.
**Available Tags:**
| Tag | Description |
| ------------------ | ------------------------------------------------- |
| `device` | All device tools |
| `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` | All touch/gesture/key/screen tools |
| `action:touch` | Click and tap actions |
| `action:gesture` | Swipe and drag gestures |
| `action:key` | Physical key presses |
| `action:screen` | Screen control (on/off) |
| `app` | All app management tools |
| `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) |
| `xpath` | All XPath-based element tools |
| `xpath:wait` | Wait for elements to appear/disappear |
| `xpath:interact` | Click and interact with elements |
| `xpath:query` | Get element info (text, bounds) |
| `xpath:gesture` | Element-specific gestures (swipe, scroll) |
| `xpath:capture` | Element screenshots |
| `gesture` | Edge swipe gestures |
| `gesture:edge` | Directional edge swipes |
| `input` | All text input tools |
| `input:text` | Text input, focusing, clearing, keyboard |
| `clipboard` | All clipboard tools |
| `clipboard:read` | Read clipboard |
| `clipboard:write` | Write clipboard |
| `screen` | All screen tools |
| `screen:mirror` | Screen mirroring (scrcpy) |
| `screen:record` | Screen recording |
| `screen:capture` | Screen screenshots |
| `system` | All system control tools |
| `system:orientation` | Device orientation control |
| `system:ui` | Notifications, quick settings, unlock |
| `system:toast` | Toast message utilities |
| `util` | Utilities (delay/sleep) |
## Testing and Debugging
### Using MCP Inspector
[MCP Inspector](https://github.com/modelcontextprotocol/inspector) is a command-line tool for testing and debugging MCP servers without requiring an AI client.
```bash
# 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](https://www.postman.com/) 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](https://learning.postman.com/docs/postman-ai/mcp-requests/overview/).
### Using cURL
You can also test the HTTP endpoint using cURL with JSON-RPC 2.0 requests:
```bash
# 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`
```json
{
"mcpServers": {
"android": {
"command": "uvx",
"args": ["uiautomator2-mcp-server", "stdio"]
}
}
}
```
If you installed the package globally, you can also use:
```json
{
"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:
```json
{
"mcpServers": {
"android": {
"command": "u2mcp",
"args": ["stdio"]
}
}
}
```
### Cherry Studio
[Cherry Studio](https://cherry-ai.com/) is a cross-platform AI desktop client with full MCP support. Ideal for Android device automation tasks.
1. Download and install [Cherry Studio](https://github.com/CherryHQ/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:
```bash
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](https://docs.cherry-ai.com/docs/en-us/advanced-basic/mcp/config).
### ChatMCP
[ChatMCP](https://github.com/daodao97/chatmcp) is an open-source AI chat client implementing the MCP protocol. Supports multiple LLM providers (OpenAI, Claude, Ollama).
1. Download and install [ChatMCP](https://github.com/daodao97/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:
```bash
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:
```json
{
"android": {
"command": "u2mcp",
"args": ["stdio"]
}
}
```
### Continue
Continue is an AI pair programmer extension for VS Code and JetBrains.
1. Install the [Continue extension](https://marketplace.visualstudio.com/items?itemName=Continue.continue)
2. Open Continue settings
3. Add to your MCP servers configuration:
```json
{
"mcpServers": {
"android": {
"command": "u2mcp",
"args": ["stdio"]
}
}
}
```
### HTTP Mode Configuration
For clients that support HTTP connections (or for remote access), start the server first:
```bash
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](https://modelcontextprotocol.io/) 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](#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
| 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/`](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:
```bash
# 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
```txt
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
------
[python]: https://www.python.org/ "Python is a programming language that lets you work quickly and integrate systems more effectively."
[pip]: https://pip.pypa.io/ "The most popular tool for installing Python packages, and the one included with modern versions of Python."
[pipx]: https://pipx.pypa.io/ "pipx is a tool to install and run Python command-line applications without causing dependency conflicts with other packages installed on the system."
[uv]: https://docs.astral.sh/uv/ "An extremely fast Python package and project manager"