Android UIAutomator2 MCP server for AI agents

MCP Android Server is a powerful automation tool that allows you to control Android devices through natural language using the Model Context Protocol (MCP). This server acts as a bridge between AI agents (like Claude, GitHub Copilot Chat, or Open Interpreter) and Android devices, enabling seamless automation through uiautomator2.

Requirements

Python 3.13 or higher
Android Debug Bridge (adb) installed and in PATH
Connected Android device with USB debugging enabled
Android device compatible with uiautomator2

Installation

Setting Up the Server

git clone https://github.com/nim444/mcp-android.git
cd mcp-android

Create and activate a virtual environment:

# Using uv (https://github.com/astral-sh/uv)
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

Install dependencies:

uv pip install

Running the Server

You can run the server using one of two methods:

Using uvicorn (Recommended):

uvicorn server:app --factory --host 0.0.0.0 --port 8000

Using MCP stdio (For AI agent integration):

python server.py

Integrating with MCP Clients

Claude Desktop Integration

Locate your Claude Desktop configuration file:
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Add the Android MCP server configuration:

{
  "mcpServers": {
    "mcp-android": {
      "type": "stdio",
      "command": "bash",
      "args": [
        "-c",
        "cd /path/to/mcp-adb && source .venv/bin/activate && python -m server"
      ]
    }
  }
}

Replace /path/to/mcp-adb with the absolute path to your cloned repository.

VS Code Integration

Create a .vscode/mcp.json file in your workspace:

{
  "servers": {
    "mcp-android": {
      "type": "stdio",
      "command": "bash",
      "args": [
        "-c",
        "cd /path/to/mcp-adb && source .venv/bin/activate && python -m server"
      ]
    }
  }
}

Manage the server using:
- Command Palette → MCP: List Servers to view and manage servers
- Command Palette → MCP: Start Server to start the server

UI Inspector

A UI inspection tool is included to help you analyze device interface structure:

Install the UI inspector:

uv pip install uiautodev

Start the inspector:

uiauto.dev

Open your browser and navigate to https://uiauto.dev

Available MCP Tools

Device Management

connect_device - Connect to an Android device and get basic info
get_device_info - Get detailed device info: serial, resolution, battery, etc.
check_adb - Check if ADB is installed and list connected devices
mcp_health - Check if the MCP server is running properly

App Management

get_installed_apps - List all installed apps with version and package info
get_current_app - Get info about the app currently in the foreground
start_app - Start an app by its package name
stop_app - Stop an app by its package name
stop_all_apps - Stop all currently running apps
clear_app_data - Clear user data/cache of a specified app
wait_activity - Wait until a specific activity appears

Screen Control

screen_on - Turn on the screen
screen_off - Turn off the screen
unlock_screen - Unlock the screen (turn on and swipe if necessary)
wait_for_screen_on - Wait asynchronously until the screen is turned on
screenshot - Take and save a screenshot from the device

UI Interaction

click - Tap on an element by text, resourceId, or description
long_click - Perform a long click on an element
send_text - Input text into currently focused field
press_key - Simulate hardware key press (e.g., home, back, menu)
swipe - Swipe from one coordinate to another
scroll_to - Scroll until a given element becomes visible
drag - Drag an element to a specific screen location

UI Analysis

get_element_info - Get info on UI elements (text, bounds, clickable, etc.)
wait_for_element - Wait for an element to appear on screen
get_toast - Get the last toast message shown on screen
dump_hierarchy - Dump the UI hierarchy of the current screen as XML

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "mcp-android" '{"type":"stdio","command":"bash","args":["-c","cd /path/to/mcp-adb && source .venv/bin/activate && python -m server"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "mcp-android": {
            "type": "stdio",
            "command": "bash",
            "args": [
                "-c",
                "cd /path/to/mcp-adb && source .venv/bin/activate && python -m server"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

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

2. Add this to your configuration file:

{
    "mcpServers": {
        "mcp-android": {
            "type": "stdio",
            "command": "bash",
            "args": [
                "-c",
                "cd /path/to/mcp-adb && source .venv/bin/activate && python -m server"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect