Android MCP

Servidor Android MCP

Un servidor MCP (Model Context Protocol) que proporciona control programático sobre dispositivos Android a través de ADB (Android Debug Bridge). Este servidor expone varias capacidades de gestión de dispositivos Android que pueden ser accedidas por clientes MCP como Claude desktop y editores de código (por ejemplo, Cursor)

Características

• 🔧 Ejecución de comandos ADB
• 📸 Captura de pantalla del dispositivo
• 🎯 Análisis de diseño de UI
• 📱 Gestión de paquetes del dispositivo

Requisitos previos

• Python 3.x
• ADB (Android Debug Bridge) instalado y configurado
• Dispositivo Android o emulador (no probado)

Instalación

1. Clona el repositorio:

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

2. Instala las dependencias: Este proyecto utiliza uv para la gestión del proyecto mediante varios métodos de instalación.

uv python install 3.11
uv sync

Configuración

El servidor admite configuración flexible de dispositivos con múltiples escenarios de uso.

Modos de selección de dispositivo

1. Selección automática (Recomendada para un solo dispositivo)

• No se necesita archivo de configuración
• Se conecta automáticamente al único dispositivo conectado
• Perfecto para desarrollo con un solo dispositivo de prueba

2. Selección manual de dispositivo

• Úsalo cuando tengas múltiples dispositivos conectados
• Especifica el dispositivo exacto en el archivo de configuración

Archivo de configuración (Opcional)

El archivo de configuración (config.yaml) es opcional. Si no está presente, el servidor seleccionará automáticamente el dispositivo si solo hay uno conectado.

Para selección automática

Simplemente asegúrate de que solo haya un dispositivo conectado y ejecuta el servidor: ¡no se necesita configuración!

Para selección manual

1. Crea un archivo de configuración:

cp config.yaml.example config.yaml

2. Edita config.yaml y especifica tu dispositivo:

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

Para la selección automática, puedes usar cualquiera de estos métodos:

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

Encontrar el serial de tu dispositivo

Para encontrar el identificador de tu dispositivo, ejecuta:

adb devices

Ejemplo de salida:

List of devices attached
13b22d7f        device
emulator-5554   device

Usa el valor de la primera columna (por ejemplo, 13b22d7f o emulator-5554) como nombre del dispositivo.

Escenarios de uso

Escenario	Configuración requerida	Comportamiento
Un solo dispositivo conectado	Ninguna	✅ Se conecta automáticamente al dispositivo
Múltiples dispositivos, quieres uno específico	config.yaml con device.name	✅ Se conecta al dispositivo especificado
Múltiples dispositivos, sin configuración	Ninguna	❌ Muestra error con los dispositivos disponibles
No hay dispositivos conectados	N/A	❌ Muestra error de "no hay dispositivos"

Nota: Si tienes múltiples dispositivos conectados y no especificas cuál usar, el servidor mostrará un mensaje de error listando todos los dispositivos disponibles.

Uso

Se necesita un cliente MCP para usar este servidor. La aplicación Claude Desktop es un ejemplo de cliente MCP. Para usar este servidor con Claude Desktop:

1. Localiza el archivo de configuración de Claude Desktop:

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

2. Agrega la configuración del servidor Android MCP a la sección mcpServers:

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

Reemplaza:

• path/to/uv con la ruta real a tu ejecutable uv
• path/to/android-mcp-server con la ruta absoluta donde clonaste este repositorio

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

Herramientas disponibles

El servidor expone las siguientes herramientas:

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
    """

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
    """

Contribuciones

¡Las contribuciones son bienvenidas!

Agradecimientos

• Construido con Model Context Protocol (MCP)