Mobile Device MCP

Un servidor MCP para interactuar con múltiples dispositivos iOS y Android al mismo tiempo.

Documentación

Mobile Device MCP

Un servidor MCP que permite a los agentes de IA controlar dispositivos iOS y Android (tocar, desplazarse, escribir, tomar capturas de pantalla, leer árboles de UI y ejecutar código). Funciona con múltiples dispositivos al mismo tiempo.

Cómo funciona

Arquitectura de tres capas:

Servidores en el dispositivo — Servidores HTTP ligeros que se ejecutan en cada dispositivo móvil (UIAutomator en Android, XCUITest en iOS) que exponen el árbol de accesibilidad y aceptan comandos de interacción.
Filtro de árbol de UI — Normaliza los árboles de UI sin procesar de ambas plataformas en una lista plana y unificada de elementos.
Servidor MCP — La interfaz externa. Gestiona el descubrimiento de dispositivos, la inicialización, la asignación de puertos y hace de proxy para las solicitudes a los servidores en el dispositivo.

Los dispositivos se inicializan en el primer uso: el servidor instala la aplicación controladora, asigna un puerto, inicia el servidor en el dispositivo y consulta periódicamente hasta que esté operativo. Después de eso, todas las llamadas a herramientas se envían a través de HTTP localhost con autenticación de token bearer por dispositivo.

Herramientas

Herramienta	Descripción
`list_devices`	Lista los dispositivos iOS y Android disponibles
`screenshot`	Captura la pantalla del dispositivo (JPEG)
`uitree`	Obtiene el árbol de elementos de UI como una lista plana, con búsqueda y límite opcionales. Los elementos fuera de pantalla se excluyen a menos que `include_invisible: true`
`tap`	Toca en las coordenadas de la pantalla
`double_tap`	Doble toque en las coordenadas de la pantalla
`long_press`	Pulsación larga en las coordenadas de la pantalla (duración configurable)
`scroll`	Desliza desde las coordenadas iniciales hasta las finales
`type_text`	Escribe texto en el elemento enfocado
`press_button`	Presiona un botón de hardware/navegación (home, back, enter, volumeUp/Down, dpadUp/Down/Left/Right/Center)
`launch_app`	Inicia una aplicación por ID de bundle / nombre de paquete
`terminate_app`	Detiene una aplicación por la fuerza
`list_apps`	Lista las aplicaciones instaladas
`install_app`	Instala una aplicación desde un archivo local del host (`.apk` para Android, `.app` para el simulador de iOS, `.app`/`.ipa` para dispositivos iOS). Reemplaza las instalaciones existentes
`run_code`	Ejecuta JavaScript en sandbox en el dispositivo (consulta run_code a continuación)

run_code

Los agentes pueden pasar código que parece UIAutomator o XCUITest, ambos siendo JavaScript internamente. El sandbox restringe (Android) operaciones de Java potencialmente peligrosas y solo permite (iOS) algunos comandos similares a XCUITest

Android: Motor Rhino con enlaces de UIAutomator — uiDevice (clic, deslizar, encontrar elementos, presionar teclas, leer información de pantalla), By (selectores), Until (condiciones de espera), console.log()
iOS: JavaScriptCore con enlaces de XCUITest — app (consultar elementos, tocar, escribir, deslizar), springboard, device, openApp(bundleId), sleep(ms), console.log()

Ambas plataformas terminan automáticamente los scripts descontrolados (bucles infinitos) y crean un sandbox nuevo por llamada.

Requisitos previos

Node.js 18+ (para ejecutar mediante npx)
Android: SDK de Android con adb en PATH
Simulador de iOS: Xcode con xcrun, simctl
Dispositivo iOS real: Xcode con xcodebuild, devicectl y iproxy (de libimobiledevice)
Compilar desde el código fuente: runtime Bun, Gradle (Android), Xcode (iOS)

Instalación

Claude Code

claude mcp add mobile-device-mcp -- npx -y @srmorete/mobile-device-mcp@latest

O con puertos personalizados:

claude mcp add mobile-device-mcp -e MDMS_PORT_ANDROID=20000 -e MDMS_PORT_IOS=21000 -- npx -y @srmorete/mobile-device-mcp@latest

Modificando `.mcp.json` (Cursor, Claude Desktop, etc.)

{
  "mcpServers": {
    "mobile-device-mcp": {
      "command": "npx",
      "args": ["-y", "@srmorete/mobile-device-mcp@latest"],
      "env": {
        "MDMS_PORT_ANDROID": "18000",           # optional
        "MDMS_PORT_IOS": "19000"                # optional
      }
    }
  }
}

Compilar desde el código fuente

git clone <repo-url>
cd mobile-device-mcp
bun install

# Build drivers for both platforms and pack tarball
./scripts/build.sh

El script de compilación compila los controladores en el dispositivo (APKs de Android mediante Gradle, paquete de pruebas de iOS mediante xcodebuild), los copia a drivers/ y crea un tarball de npm.

Para ejecutar localmente durante el desarrollo:

bun run start           # Start the MCP server
bun test                # Run the test suite

Configuración

Variable de entorno	Predeterminado	Descripción
`MDMS_PORT_ANDROID`	18000	Puerto base para servidores en dispositivos Android
`MDMS_PORT_IOS`	19000	Puerto base para servidores en dispositivos iOS

Los puertos se asignan secuencialmente: el primer dispositivo Android obtiene 18000, el segundo 18001, y así sucesivamente. Lo mismo para iOS comenzando en 19000.

Agradecimientos

El servidor Mobile Device MCP se apoya en hombros de gigantes como mobile-mcp y Maestro. Se utilizaron como inspiración, pero se reformuló el enfoque actual para ser multidispositivo y con soporte fluido de Native/WebView (especialmente en Android).

Licencia

MIT

Mobile Device MCP

Documentación