MobAI MCP

Servidor MobAI MCP

Servidor MCP (Model Context Protocol) para MobAI — automatización de dispositivos móviles impulsada por IA. Permite que los asistentes de IA (Claude Code, Cursor, Windsurf, Cline y otras herramientas compatibles con MCP) controlen dispositivos Android e iOS, emuladores y simuladores mediante una interfaz unificada basada en DSL.

Cómo funciona

Toda la interacción con dispositivos se agrupa a través de una herramienta principal: execute_dsl. En lugar de exponer docenas de herramientas de grano fino (tocar, deslizar, escribir…), el servidor acepta un script JSON que describe una secuencia de acciones con predicados, aserciones, esperas y ramas condicionales. Esto mantiene bajos los tiempos de ida y vuelta y codifica estrategias de reintento/fallo en el lado del servidor.

Un pequeño conjunto de herramientas complementarias gestiona el descubrimiento de dispositivos, capturas de pantalla, gestión de aplicaciones y ejecución de archivos de prueba .mob.

Requisitos previos

• Node.js 18+
• Aplicación de escritorio MobAI ejecutándose localmente (API HTTP en 127.0.0.1:8686)
• Un dispositivo Android o iOS conectado, emulador o simulador

Instalación

Claude Code

claude mcp add mobai -- npx -y mobai-mcp

Cursor

Añade a .cursor/mcp.json:

{
  "mcpServers": {
    "mobai": {
      "command": "npx",
      "args": ["-y", "mobai-mcp"]
    }
  }
}

Claude Desktop

Añade a ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "mobai": {
      "command": "npx",
      "args": ["-y", "mobai-mcp"]
    }
  }
}

Windsurf / Cline / otros clientes MCP

El servidor usa stdio — utiliza la configuración MCP genérica de tu cliente:

{
  "command": "npx",
  "args": ["-y", "mobai-mcp"]
}

Herramientas

Gestión de dispositivos

Herramienta	Descripción
list_devices	Lista todos los dispositivos Android e iOS conectados
get_device	Obtiene detalles sobre un dispositivo específico
start_bridge	Inicia el puente de automatización en un dispositivo (requerido antes de la interacción)
stop_bridge	Detiene el puente de automatización
claim_device	Reclama el uso exclusivo de un dispositivo para esta sesión (generalmente opcional: actuar sobre un dispositivo no reclamado lo reclama automáticamente)
release_device	Libera una o todas las concesiones de dispositivo mantenidas por esta sesión

Capturas de pantalla

Herramienta	Descripción
get_screenshot	Captura rápida y de baja calidad para análisis visual por LLM (puede reducirse; la respuesta incluye el factor de escala)
save_screenshot	PNG de calidad completa en disco para informes, depuración o uso compartido

Aplicaciones

Herramienta	Descripción
list_apps	Lista las aplicaciones instaladas en el dispositivo
install_app	Instala un .apk o .ipa desde una ruta de archivo local
uninstall_app	Desinstala una aplicación por ID de paquete / nombre de paquete
debug_app	Lanza una aplicación en modo depuración y escribe stdout/stderr en un archivo de registro

Automatización

Herramienta	Descripción
execute_dsl	Herramienta principal. Ejecuta un lote de pasos DSL: tocar, escribir, deslizar, observar, aserciones, automatización web, métricas, grabación de pantalla y más.

Gestión de pruebas

Las pruebas son archivos .mob en disco dentro de directorios de proyecto. Puedes leerlas, escribirlas y editarlas directamente usando las herramientas de sistema de archivos de tu asistente — MobAI observa los cambios y actualiza la interfaz en vivo. MCP solo es necesario para descubrir proyectos y ejecutar pruebas.

Herramienta	Descripción
test_get_active	Obtiene el directorio del proyecto de prueba activo y sus casos .mob
test_list_projects	Lista todos los directorios de proyectos de prueba conocidos con sus casos .mob
test_run	Ejecuta un caso de prueba .mob en un dispositivo (project_dir + case_path + device_id, params opcional para sustitución de ${name})

Recursos

Léelos antes de intentar cualquier interacción con dispositivos — describen el esquema DSL, el conjunto de acciones, los predicados, las estrategias de fallo y la sintaxis de .mob.

URI	Propósito
mobai://reference/device-automation	Cómo controlar dispositivos — guía, todas las acciones DSL, predicados y estrategias de fallo
mobai://reference/testing	Flujo de trabajo de pruebas, reglas, correcciones de errores y sintaxis de scripts .mob

Ejemplo

Abre la aplicación de Configuración de iOS, navega a Wi-Fi y verifica que el interruptor existe:

{
  "version": "0.2",
  "steps": [
    {"action": "open_app", "bundle_id": "com.apple.Preferences"},
    {"action": "wait_for", "predicate": {"text": "Settings"}, "timeout_ms": 3000},
    {"action": "tap", "predicate": {"text_contains": "Wi-Fi"}},
    {"action": "wait_for", "predicate": {"type": "switch"}, "timeout_ms": 3000},
    {"action": "assert_exists", "predicate": {"type": "switch"}},
    {"action": "observe", "include": ["ui_tree"]}
  ]
}

Pasa esto como el argumento commands (una cadena JSON) a execute_dsl junto con un device_id de list_devices.

Solución de problemas

"Connection refused" / "Could not reach the MobAI desktop app" — Asegúrate de que la aplicación de escritorio MobAI esté instalada y ejecutándose, y que la API sea accesible en http://127.0.0.1:8686. Si aún no la tienes, descárgala e instálala desde https://mobai.run/download.

"Bridge not running" — Llama a start_bridge primero. El puente de iOS puede tardar hasta un minuto en iniciarse.

Capturas de pantalla no visibles — get_screenshot guarda en /tmp/mobai/screenshots/ por defecto y devuelve la ruta del archivo. Usa la capacidad de lectura de archivos de tu asistente para verlas. Las capturas de pantalla DSL observe se extraen de la respuesta y se guardan en el mismo directorio.

Desarrollo

git clone https://github.com/MobAI-App/mobai-mcp.git
cd mobai-mcp
npm install
npm run build
node dist/index.js

Licencia

Apache 2.0 — consulta LICENSE.