mcp-server-android 0.3.1

MCP server for Android device automation via ADB

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

• 🔧 ADB Command Execution
• 📸 Device Screenshot Capture
• 🎯 UI Layout Analysis
• 📱 Device Package Management
• 🚀 NEW: Automatic Emulator Startup
• 🎮 NEW: Emulator Management Tools

Prerequisites

• Python 3.11+
• ADB (Android Debug Bridge) installed and configured
• Android device (physical or emulator)

Installation

Quick Install (Recommended)

# Using uvx (no installation needed)
uvx mcp-server-android

# Or using pip
pip install mcp-server-android

# Or using uv tool
uv tool install mcp-server-android

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

Environment Variables

You can configure the server using environment variables:

• ANDROID_DEVICE_SERIAL - Specify the device serial (overrides config file)
• ANDROID_MCP_CONFIG - Path to custom config file (default: config.yaml)
• ANDROID_AUTO_START_EMULATOR - Enable/disable auto-start emulator (default: true)

Example:

export ANDROID_DEVICE_SERIAL="emulator-5554"
uvx mcp-server-android

Device Selection Modes

1. Automatic Selection (Recommended for single device)

• No configuration file needed
• Automatically connects to the only connected device
• Perfect for development with a single test device

2. Manual Device Selection

• Use when you have multiple devices connected
• Specify exact device in configuration file

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 with emulator start instructions

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.

Emulator Support

The server provides comprehensive emulator support with automatic startup capabilities:

Automatic Emulator Startup (New!)

By default, if no devices are connected, the server will:

1. Detect available Android Virtual Devices (AVDs)
2. Automatically start the first available emulator
3. Wait for it to boot (up to 60 seconds)
4. Connect to it automatically

This behavior can be disabled by:

• Setting ANDROID_AUTO_START_EMULATOR=false environment variable
• Or in config.yaml: device.auto_start_emulator: false

Manual Emulator Management

When auto-start is disabled or fails, the server:

Example error message with emulator suggestions:

No devices connected. Please:
- Connect a physical device with USB debugging enabled, OR
- Start an emulator: ~/Library/Android/sdk/emulator/emulator -avd <name>
  Available AVDs: Pixel_8_API_35, Nexus_5X_API_28

Automatic ADB Detection

The server now automatically searches for ADB in common installation locations if it's not in your PATH:

• macOS: ~/Library/Android/sdk/platform-tools, /opt/homebrew/bin, /usr/local/bin
• Linux: ~/Android/sdk/platform-tools, /usr/bin
• Android Studio installations

This means the server will work even when launched from environments with limited PATH access (like Claude Desktop or MCP routers).

Usage

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

MetaMCP Integration

To use with MetaMCP, add this to your MetaMCP configuration:

{
  "mcpServers": {
    "android": {
      "command": "/path/to/android-mcp-server/run-mcp-server.sh"
    }
  }
}

For paths with spaces, use the wrapper script included in the package. See METAMCP.md for detailed setup instructions.

Claude Desktop Configuration

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": "uvx",
      "args": ["mcp-server-android"],
      "env": {
        "ANDROID_DEVICE_SERIAL": "your-device-serial",  // Optional
        "ANDROID_AUTO_START_EMULATOR": "true"  // Optional, default is true
      }
    }
  }
}

Or if installed with pip:

{
  "mcpServers": {
    "android": {
      "command": "mcp-server-android",
      "args": []
    }
  }
}

https://github.com/user-attachments/assets/c45bbc17-f698-43e7-85b4-f1b39b8326a8

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_shell_command(command: str) -> str:
    """
    Executes an ADB shell command and returns the output.
    Args:
        command (str): The ADB shell 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
    """

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

def get_package_action_intents(package_name: str) -> list[str]:
    """
    Get all non-data actions from Activity Resolver Table for a package
    Args:
        package_name (str): The name of the package to get actions for
    Returns:
        list[str]: A list of all non-data actions from the Activity Resolver
        Table for the package
    """

Emulator Management Tools (New!)

def list_devices() -> dict:
    """
    List all connected Android devices (physical and emulators).
    Returns device serials and their types.
    """

def list_emulators() -> dict:
    """
    List available Android Virtual Devices (AVDs) that can be started.
    Returns available AVD names and emulator command path.
    """

def start_emulator_avd(avd_name: str | None = None, headless: bool = False) -> dict:
    """
    Start an Android emulator with the specified AVD.
    Args:
        avd_name: Name of the AVD to start. If None, uses first available.
        headless: If True, starts emulator without GUI (faster, uses less resources)
    Returns:
        Status information including success, device_serial, and message
    """

def stop_emulator(device_serial: str | None = None) -> dict:
    """
    Stop a running Android emulator.
    Args:
        device_serial: Serial of the emulator to stop (e.g., 'emulator-5554').
                      If None, stops all emulators.
    Returns:
        Status information
    """

Contributing

Contributions are welcome!

Acknowledgments

• Built with Model Context Protocol (MCP)