Android MCP Server provides programmatic control over Android devices through ADB (Android Debug Bridge), enabling AI assistants to manage and interact with Android devices and emulators remotely. Key features of Android MCP Server: - Execute ADB commands directly on connected Android devices - Capture device screenshots for visual testing and debugging - Analyze UI layout structures for accessibility testing and automation - Manage installed packages (apps) on Android devices - Automatic device selection when only one device is detected - Support for multiple devices with optional manual configuration via config.yaml

Android MCP Server

An MCP (Model Context Protocol) server that provides programmatic control over Android devices through ADB (Android Debug Bridge). This server exposes various Android device management capabilities that can be accessed by MCP clients like Claude desktop and Code editors (e.g. Cursor)

Features

Prerequisites

Installation

1. Clone the repository:

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

2. Install dependencies: This project uses uv for project management via various methods of installation.

uv python install 3.11
uv sync

Configuration

The server supports flexible device configuration with multiple usage scenarios.

Device Selection Modes

1. Automatic Selection (Recommended for single device)

2. Manual Device Selection

Configuration File (Optional)

The configuration file (config.yaml) is optional. If not present, the server will automatically select the device if only one is connected.

#### For Automatic Selection

Simply ensure only one device is connected and run the server - no configuration needed!

#### For Manual Selection

1. Create a configuration file:

cp config.yaml.example config.yaml

2. Edit config.yaml and specify your device:

device:
  name: "your-device-serial-here" # Device identifier from 'adb devices'

For auto-selection, you can use any of these methods:

device:
  name: null              # Explicit null (recommended)
  # name: ""              # Empty string  
  # name:                 # Or leave empty/comment out

Finding Your Device Serial

To find your device identifier, run:

adb devices

Example output:

List of devices attached
13b22d7f        device
emulator-5554   device

Use the first column value (e.g., 13b22d7f or emulator-5554) as the device name.

Usage Scenarios

| Scenario | Configuration Required | Behavior | |----------|----------------------|----------| | Single device connected | None | ✅ Auto-connects to the device | | Multiple devices, want specific one | config.yaml with device.name | ✅ Connects to specified device | | Multiple devices, no config | None | ❌ Shows error with available devices | | No devices connected | N/A | ❌ Shows "no devices" error |

Note: If you have multiple devices connected and don't specify which one to use, the server will show an error message listing all available devices.

Usage

An MCP client is needed to use this server. The Claude Desktop app is an example of an MCP client. To use this server with Claude Desktop:

1. Locate your Claude Desktop configuration file:

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

2. Add the Android MCP server configuration to the mcpServers section:

{
  "mcpServers": {
    "android": {
      "command": "path/to/uv",
      "args": ["--directory", "path/to/android-mcp-server", "run", "server.py"]
    }
  }
}

Replace:

Available Tools

The server exposes the following tools:

def get_packages() -> str:
    """
    Get all installed packages on the device.
    Returns:
        str: A list of all installed packages on the device as a string
    """

def execute_adb_command(command: str) -> str:
    """
    Executes an ADB command and returns the output.
    Args:
        command (str): The ADB command to execute
    Returns:
        str: The output of the ADB command
    """

def get_uilayout() -> str:
    """
    Retrieves information about clickable elements in the current UI.
    Returns a formatted string containing details about each clickable element,
    including their text, content description, bounds, and center coordinates.
    Returns:
        str: A formatted list of clickable elements with their properties
    """

```python def get_screenshot() -> Image: """ Takes a screenshot of the device and returns it. Returns: Image: the screenshot