Agente Android de MCP

Este proyecto proporciona un servidor MCP (Protocolo de Contexto de Modelo) para automatizar dispositivos Android mediante uiautomator2 . Está diseñado para integrarse fácilmente con agentes de IA como GitHub Copilot Chat, Claude o Open Interpreter para controlar dispositivos Android mediante lenguaje natural.

Demostración rápida

Requisitos

Python 3.13 o superior
Android Debug Bridge (adb) instalado y en PATH
Dispositivo Android conectado con depuración USB habilitada
Dispositivo Android compatible con uiautomator2

Características

Iniciar, detener y administrar aplicaciones por nombre de paquete
Recuperar aplicaciones instaladas y la aplicación actual en primer plano
Toque, deslice, desplácese, arrastre y realice interacciones de IU
Obtenga información del dispositivo, resolución de pantalla, estado de la batería y más
Capturar capturas de pantalla o los últimos mensajes de brindis
Desbloquear, activar o suspender la pantalla programáticamente
Borrar los datos de la aplicación y esperar las actividades
Incluye un control de salud y una herramienta de diagnóstico adb

Casos de uso

Perfecto para:

Agentes de IA que necesitan interactuar con dispositivos reales
Configuraciones de control de dispositivos remotos
Herramientas de control de calidad automatizadas
Marcos de bots de Android
Pruebas y automatización de UI
Gestión y monitorización de dispositivos

Instalación

1. Clonar el repositorio

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

2. Crear y activar el entorno virtual

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

3. Instalar dependencias

uv pip install

Ejecución del servidor

Opción 1: Usar uvicorn (recomendado)

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

Opción 2: Usar MCP stdio (para la integración del agente de IA)

python server.py

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:

Localice su archivo de configuración de Claude Desktop

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

Agregue la configuración del servidor MCP de Android a la sección mcpServers

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

Reemplace /path/to/mcp-adb con la ruta absoluta donde clonó este repositorio. Por ejemplo: /Users/username/Projects/mcp-adb

Uso con VS Code

También puedes usar este servidor MCP con el modo agente de VS Code (requiere VS Code 1.99 o posterior). Para configurarlo:

Crea un archivo .vscode/mcp.json en tu espacio de trabajo:

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

Reemplace /path/to/mcp-adb con la ruta absoluta a donde clonó este repositorio.

Después de agregar la configuración, puede administrar el servidor mediante:

Paleta de comandos → MCP: List Servers para ver y administrar servidores configurados
Paleta de comandos → MCP: Start Server para iniciar el servidor
Las herramientas del servidor estarán disponibles en el chat del modo agente de VS Code

Inspector de interfaz de usuario

El proyecto incluye soporte para uiauto.dev, una poderosa herramienta de inspección de UI para ver y analizar la estructura de la interfaz de su dispositivo.

Instalar el inspector de UI:

uv pip install uiautodev

Iniciar el inspector:

uiauto.dev

Abra su navegador y navegue a https://uiauto.dev

Herramientas MCP disponibles

Nombre de la herramienta	Descripción
`mcp_health`	Compruebe si el servidor MCP está funcionando correctamente
`connect_device`	Conéctese a un dispositivo Android y obtenga información básica
`get_installed_apps`	Lista de todas las aplicaciones instaladas con información de la versión y el paquete
`get_current_app`	Obtenga información sobre la aplicación que se encuentra actualmente en primer plano
`start_app`	Iniciar una aplicación por el nombre de su paquete
`stop_app`	Detener una aplicación por su nombre de paquete
`stop_all_apps`	Detener todas las aplicaciones que se estén ejecutando actualmente
`screen_on`	Encender la pantalla
`screen_off`	Apaga la pantalla
`get_device_info`	Obtenga información detallada del dispositivo: serie, resolución, batería, etc.
`press_key`	Simular la pulsación de teclas de hardware (por ejemplo, `home` , `back` , `menu` , etc.)
`unlock_screen`	Desbloquear la pantalla (enciéndela y deslízala si es necesario)
`check_adb`	Compruebe si ADB está instalado y enumere los dispositivos conectados
`wait_for_screen_on`	Esperar asincrónicamente hasta que se encienda la pantalla
`click`	Toque un elemento por `text` , `resourceId` o `description`
`long_click`	Realizar un clic largo sobre un elemento
`send_text`	Ingrese texto en el campo actualmente enfocado (opcionalmente, borre primero)
`get_element_info`	Obtenga información sobre los elementos de la interfaz de usuario (texto, límites, elementos en los que se puede hacer clic, etc.)
`swipe`	Desliza el dedo de una coordenada a otra
`wait_for_element`	Esperar a que aparezca un elemento en la pantalla
`screenshot`	Tomar y guardar una captura de pantalla del dispositivo
`scroll_to`	Desplácese hasta que un elemento determinado se vuelva visible
`drag`	Arrastre un elemento a una ubicación específica de la pantalla
`get_toast`	Obtener el último mensaje de brindis que se muestra en la pantalla
`clear_app_data`	Borrar datos de usuario/caché de una aplicación específica
`wait_activity`	Esperar hasta que aparezca una actividad específica
`dump_hierarchy`	Volcar la jerarquía de la interfaz de usuario de la pantalla actual como XML

Licencia

Este proyecto está licenciado bajo la licencia MIT: consulte el archivo de LICENCIA para obtener más detalles.

MCP Android Agent

Integrations