MCP Android Agent

Automatiza dispositivos Android usando la biblioteca uiautomator2, que requiere adb y un dispositivo conectado.

Documentación

MCP Android Agent

Este proyecto proporciona un servidor MCP (Model Context Protocol) para automatizar dispositivos Android usando uiautomator2. Está diseñado para conectarse fácilmente a agentes de IA como GitHub Copilot Chat, Claude u Open Interpreter para controlar dispositivos Android mediante lenguaje natural.

Arquitectura Modular

El servidor ha sido refactorizado en una arquitectura modular y limpia, con herramientas organizadas por funcionalidad:

mcp-android-server-python/
├── server.py                    # Main server (61 lines - clean & focused)
├── server_original_backup.py    # Backup of original monolithic version
└── tools/                       # 🆕 Modular tools package
    ├── __init__.py             # Central registration & imports
    ├── device_tools.py         # Device connection & status tools
    ├── app_tools.py            # Application management tools
    ├── screen_tools.py         # Screen control & unlock tools
    ├── input_tools.py          # User input simulation (click, swipe, text)
    ├── inspection_tools.py     # UI inspection & screenshots
    └── advanced_tools.py       # Advanced features (toast, activity wait)

Beneficios de la Arquitectura Modular

Mantenibilidad: Fácil de añadir/modificar/eliminar herramientas sin tocar el servidor principal
Organización: Herramientas agrupadas lógicamente por funcionalidad
Pruebas: Los módulos de herramientas individuales pueden probarse por separado
Reutilización: Los módulos de herramientas pueden reutilizarse en otros proyectos
Escalabilidad: Se pueden añadir nuevas categorías de herramientas como módulos separados
Código Limpio: El servidor principal se redujo de 1321 líneas a 61 líneas

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

Gestión de Dispositivos

Detección Inteligente de Dispositivos: Encuentra y conecta automáticamente a los dispositivos disponibles
Información Completa del Dispositivo: Obtén serial, resolución, batería, IP WiFi, versión de Android
Diagnósticos ADB: Verifica la disponibilidad de ADB y el estado de la conexión
Monitoreo de Salud: Comprobaciones de salud integradas del servidor

Gestión de Aplicaciones

Descubrimiento de Aplicaciones: Lista todas las aplicaciones instaladas (aplicaciones del sistema y del usuario)
Control del Ciclo de Vida de Aplicaciones: Iniciar, detener, forzar detención de aplicaciones por nombre de paquete
Monitoreo del Estado de Aplicaciones: Rastrea la aplicación y actividad en primer plano actual
Gestión de Datos: Limpia datos/caché de aplicaciones para pruebas

Control de Pantalla y Visualización

Gestión de Energía de Pantalla: Enciende/apaga la pantalla programáticamente
Desbloqueo Inteligente: Desbloqueo automático de pantalla con métodos estándar
Monitoreo del Estado de Pantalla: Espera la activación de la pantalla (soporte asíncrono)

Simulación de Entrada de Usuario

Interacciones de Precisión: Clic por texto, ID de recurso o descripción de contenido
Gestos Avanzados: Clic largo, deslizamiento, operaciones de arrastre
Entrada de Texto: Entrada de texto inteligente con limpieza opcional de campos
Teclas de Hardware: Simular teclas de inicio, atrás, menú, volumen

Inspección y Depuración de UI

Análisis de Elementos: Obtén propiedades detalladas y límites de elementos de UI
Captura de Pantalla: Toma capturas de pantalla para depuración y documentación
Jerarquía de UI: Exporta la estructura completa de la pantalla como XML
Espera Inteligente: Espera a que los elementos aparezcan con tiempos de espera personalizados
Detección de Desplazamiento: Auto-desplazamiento para encontrar elementos en listas largas

Capacidades Avanzadas

Detección de Toast: Captura mensajes de toast del sistema para verificación
Monitoreo de Actividades: Espera actividades específicas de Android
Operaciones en Segundo Plano: Soporte asíncrono para operaciones que consumen tiempo

Casos de Uso

Perfecto para:

Agentes de IA que necesitan interactuar con dispositivos reales
Configuraciones de control remoto de dispositivos
Herramientas automatizadas de control de calidad
Marcos de trabajo para bots de Android
Pruebas y automatización de UI
Gestión y monitoreo 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

Ejecutar el Servidor

El servidor soporta dos modos de transporte diferentes según tu caso de uso:

Opción 1: MCP stdio (Para Integración con Agentes de IA)

Este es el modo estándar para integrarse con agentes de IA como Claude Desktop, VS Code u otros clientes MCP.

# Edit server.py to use stdio mode (default commented out)
# Uncomment the stdio section and comment out http section

# Then run:
uv run python server.py

Opción 2: HTTP Transmisible (Para Integración Web/API)

Este modo ejecuta el servidor como una API HTTP, útil para aplicaciones web, pruebas con curl o llamadas HTTP directas.

# Current default configuration - runs as HTTP server
uv run python server.py

# Server will be available at: http://localhost:8080

Cambiar Entre Modos

Edita server.py y modifica la sección if __name__ == "__main__"::

Para modo stdio (agentes de IA):

if __name__ == "__main__":
    mcp.run(
        transport="stdio",
        show_banner=False,
    )

Para modo HTTP (API web):

if __name__ == "__main__":
    mcp.run(
        transport="streamable-http",
        host="0.0.0.0",
        port=8080,
    )

Uso

Para Integración con Agentes de IA (Claude Desktop, VS Code, etc.)

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

Importante: Para la integración con agentes de IA, asegúrate de configurar el servidor en modo stdio (ver "Opción 1" arriba).

Para usar este servidor con Claude Desktop:

Localiza tu archivo de configuración de Claude Desktop

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

Añade 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 && uv run python server.py"
      ]
    }
  }
}

Reemplaza /path/to/mcp-adb con la ruta absoluta donde clonaste 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 superior). 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 && uv run python server.py"
      ]
    }
  }
}

Reemplaza /path/to/mcp-adb con la ruta absoluta donde clonaste este repositorio.

Después de añadir la configuración, puedes gestionar el servidor usando:

Paleta de Comandos → MCP: List Servers para ver y gestionar los 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

Para Integración con API HTTP (Llamadas API Directas)

Cuando se ejecuta en modo HTTP (Opción 2), puedes interactuar con el servidor directamente mediante solicitudes HTTP:

# Check if server is running
curl http://localhost:8080/

# List available tools (you'll need to implement proper tool discovery endpoints)
# This depends on your FastMCP version and configuration

Casos de Uso para el Modo HTTP:

Aplicaciones web con automatización de Android
Herramientas de prueba que no pueden usar stdio
Integración directa de API con otros servicios
Depuración y desarrollo con curl/Postman

Inspector de UI

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

Instala el inspector de UI:

uv pip install uiautodev

Inicia el inspector:

uiauto.dev

Abre tu navegador y navega a https://uiauto.dev

Herramientas MCP Disponibles

Herramientas de Gestión de Dispositivos

Nombre de la Herramienta	Descripción
`mcp_health`	Verifica si el servidor MCP está funcionando correctamente
`get_device_status`	Obtén el estado completo del dispositivo e información de preparación
`connect_device`	Conéctate a un dispositivo Android y obtén información básica
`get_device_info`	Obtén información detallada del dispositivo: serial, resolución, batería, etc.
`check_adb_and_list_devices`	Verifica si ADB está instalado y lista los dispositivos conectados

Herramientas de Gestión de Aplicaciones

Nombre de la Herramienta	Descripción
`get_installed_apps`	Lista todas las aplicaciones instaladas con versión e información del paquete
`get_current_app`	Obtén información sobre la aplicación actualmente en primer plano
`start_app`	Inicia una aplicación por su nombre de paquete
`stop_app`	Detén una aplicación por su nombre de paquete
`stop_all_apps`	Detén todas las aplicaciones actualmente en ejecución
`clear_app_data`	Limpia los datos/caché de usuario de una aplicación especificada

Herramientas de Control de Pantalla

Nombre de la Herramienta	Descripción
`screen_on`	Enciende la pantalla
`screen_off`	Apaga la pantalla
`unlock_screen`	Desbloquea la pantalla (enciende y desliza si es necesario)
`wait_for_screen_on`	Espera asincrónicamente hasta que la pantalla esté encendida

Herramientas de Entrada de Usuario

Nombre de la Herramienta	Descripción
`press_key`	Simula la pulsación de teclas de hardware (p. ej. `home`, `back`, `menu`, etc.)
`click`	Toca un elemento por `text`, `resourceId` o `description`
`long_click`	Realiza un clic largo en un elemento
`send_text`	Ingresa texto en el campo actualmente enfocado (opcionalmente limpiando antes)
`swipe`	Desliza de una coordenada a otra
`drag`	Arrastra un elemento a una ubicación específica de la pantalla

Herramientas de Inspección

Nombre de la Herramienta	Descripción
`get_element_info`	Obtén información sobre elementos de UI (texto, límites, clicable, etc.)
`wait_for_element`	Espera a que un elemento aparezca en pantalla
`scroll_to`	Desplázate hasta que un elemento dado sea visible
`screenshot`	Toma y guarda una captura de pantalla del dispositivo
`dump_hierarchy`	Vuelca la jerarquía de UI de la pantalla actual como XML

Herramientas Avanzadas

Nombre de la Herramienta	Descripción
`get_toast`	Obtén el último mensaje de toast mostrado en pantalla
`wait_activity`	Espera hasta que aparezca una actividad específica