Android Debug Bridge

🚀 Android MCP Server

An MCP (Model Context Protocol) server that enables programmatic control of Android devices via Android Debug Bridge (ADB). It offers a variety of Android device management functions accessible through MCP clients (e.g., Claude Desktop) and code editors (e.g., Cursor).

🚀 Quick Start

The Android MCP Server provides programmatic control of Android devices through the Model Context Protocol (MCP) via ADB. It offers multiple Android device management functions accessible via MCP clients and code editors.

✨ Features

• 🔧 Execute ADB commands.
• 📸 Capture device screenshots.
• 🎯 Analyze user interface layouts.
• 📱 Manage device software packages.

📦 Installation

Prerequisites

• Python 3.x
• Installed and configured Android Debug Bridge (ADB)
• An Android device or emulator (untested)

Steps

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 and can be installed in various ways.

uv python install 3.11
uv sync

📚 Documentation

Configuration

The server uses a simple YAML configuration file (config.yaml) to specify the target Android device.

Custom Configuration

1. Create a new configuration file:

touch config.yaml

2. Configure your device:

device:
  name: "google-pixel-7-pro:5555" # Your device identifier from 'adb devices'

Usage

You need an MCP client to use this server. The Claude Desktop app is an example. To use this server with Claude Desktop:

1. Find the location of 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 the following:

• path/to/uv with the actual path to your uv executable.
• path/to/android-mcp-server with the actual absolute path where you cloned this repository.

GitHub Resource Attachment

Available Tools

The server exposes the following tools:

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

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

def get_window_bounds(package_name: str, activity_name: str) -> tuple[int, int, int, int]:
    """
    Get the bounding coordinates of the specified application window.
    Args:
        package_name (str): The application package name.
        activity_name (str): The activity name.
    Returns:
        tuple[int, int, int, int]: A tuple of top-left x, top-left y, bottom-right x, bottom-right y.
    """

def get_window_size(package_name: str, activity_name: str) -> tuple[int, int]:
    """
    Get the size of the specified application window.
    Args:
        package_name (str): The application package name.
        activity_name (str): The activity name.
    Returns:
        tuple[int, int]: A tuple of window width and height.
    """

def get_display_metrics(package_name: str, activity_name: str) -> dict:
    """
    Get the display metrics of the specified application window.
    Args:
        package_name (str): The application package name.
        activity_name (str): The activity name.
    Returns:
        dict: A dictionary containing information such as density, width, and height.
    """

def get_views(package_name: str, activity_name: str) -> list:
    """
    Get all views in the specified application window.
    Args:
        package_name (str): The application package name.
        activity_name (str): The activity name.
    Returns:
        list: A list containing view information.
    """

🤝 Contribution

If you'd like to contribute, please refer to the project repository on GitHub.

🙏 Acknowledgments

Thank you for using this project! If you encounter any issues or have suggestions, please feel free to share.