expo-mcp

Servidor MCP para la automatización de aplicaciones Expo/React Native con integración de Maestro.

Características

• Arquitectura basada en sesiones: start_session inicia Expo, vincula un dispositivo y adquiere un arrendamiento; sin gestión manual de ID de dispositivo.

• Arrendamiento de dispositivo con TTL: Arrendamiento de 2 minutos renovado automáticamente en cada llamada a la herramienta de dispositivo; expira tras la inactividad para que otras instancias puedan usar el dispositivo.

• Coordinación entre instancias: Múltiples instancias de MCP pueden ejecutarse simultáneamente sin conflictos de dispositivos.

• Gestión del servidor de desarrollo de Expo: Iniciar/detener/recargar el servidor de desarrollo de Expo.

• Integración con Maestro: Herramientas completas de automatización de interfaz de usuario (toque, entrada, captura de pantalla, etc.).

Instalación

Como plugin de Claude Code (Recomendado)

Dos comandos, luego reinicia:

# 1. Install the plugin. Just dismiss the "Expo App Directory" prompt
#    (or leave it empty) — the next step configures it for you.
/plugin marketplace add DaveDev42/expo-mcp
/plugin install expo-mcp --scope project

# 2. One-shot installer. Runs environment checks, auto-detects the Expo
#    app directory, and writes the userConfig directly into
#    .claude/settings.json. No /plugin UI round-trip needed.
/expo-mcp:install                     # auto-detect
/expo-mcp:install apps/mobile         # monorepo: pass the path explicitly

Luego reinicia Claude Code y todas las herramientas, agentes y habilidades estarán listos.

Flags del instalador:

/expo-mcp:install apps/mobile --global        # write to ~/.claude/settings.json
/expo-mcp:install --scaffold-maestro          # also create a starter maestro/
/expo-mcp:install --skip-doctor               # skip prerequisite checks

El instalador ejecuta scripts de Node empaquetados (doctor.mjs, detect-app-dir.mjs, scaffold-maestro.mjs) desde el directorio del plugin. Claude Code te pedirá que apruebes cada uno la primera vez que se ejecute; aprúebalos para continuar.

Si prefieres preaprobar los scripts (sin avisos), añade esto a .claude/settings.local.json en tu proyecto, reemplazando <PATH> con la ruta absoluta mostrada por Claude Code la primera vez que se ejecuta cada script:

{
  "permissions": {
    "allow": [
      "Bash(node <PATH>/doctor.mjs:*)",
      "Bash(node <PATH>/detect-app-dir.mjs:*)",
      "Bash(node <PATH>/scaffold-maestro.mjs:*)"
    ]
  }
}

La instalación del plugin configura automáticamente:

• El servidor MCP expo (no se necesita .mcp.json manual)

• Un agente de QA (qa) para pruebas automatizadas de aplicaciones móviles

• Un agente de escritura de flujos (flow-writer) para crear flujos de prueba YAML de Maestro

• Una guía de uso (/expo-guide) con referencia de herramientas y mejores prácticas

• Un hook de validación que advierte sobre veredictos de QA PASS sin evidencia de ejecución

Solo como servidor MCP

Este proyecto se distribuye solo a través de GitHub (el nombre expo-mcp en npm pertenece a un paquete diferente y no relacionado; no lo uses). Ejecútalo mediante la referencia de GitHub:

npx -y github:DaveDev42/expo-mcp

Uso con Claude Code

Configuración manual de MCP

Si no usas el plugin, añade a tu .mcp.json:

{
  "mcpServers": {
    "expo": {
      "command": "npx",
      "args": ["-y", "github:DaveDev42/expo-mcp"]
    }
  }
}

Configuración de Monorepo

Usa un argumento posicional para especificar el directorio de la aplicación:

{
  "mcpServers": {
    "expo": {
      "command": "npx",
      "args": ["-y", "github:DaveDev42/expo-mcp", "apps/mobile"]
    }
  }
}

Dispositivo específico

Fija un simulador o emulador específico con --device-id:

{
  "mcpServers": {
    "expo": {
      "command": "npx",
      "args": ["-y", "github:DaveDev42/expo-mcp", "--device-id=6D192F60-1234-5678-ABCD-000000000000"]
    }
  }
}

Filtrado de herramientas

Excluye herramientas específicas con --exclude-tools:

{
  "mcpServers": {
    "expo": {
      "command": "npx",
      "args": ["-y", "github:DaveDev42/expo-mcp", "apps/mobile", "--exclude-tools=list_devices"]
    }
  }
}

O expón solo herramientas específicas con --tools:

{
  "mcpServers": {
    "expo": {
      "command": "npx",
      "args": ["-y", "github:DaveDev42/expo-mcp", "--tools=start_session,stop_session,take_screenshot"]
    }
  }
}

Referencia de CLI

Usage: expo-mcp [app-dir] [options]

Arguments:
  app-dir                      Path to Expo app directory (default: cwd)

Options:
  --device-id=<id>             Specific device to use (iOS simulator UUID or Android serial)
  --exclude-tools=tool1,tool2  Exclude specific tools from the MCP server
  --tools=tool1,tool2          Only expose specific tools
  -h, --help                   Show help message
  -v, --version                Show version number

Inicio rápido

# 1. Start session (launches Expo + binds device + acquires lease)
start_session({ target: "ios-simulator" })

# 2. Use tools directly (no device_id needed!)
take_screenshot()
tap_on({ text: "Login" })
input_text({ text: "hello@example.com" })
press_key({ key: "Enter" })
scroll({ direction: "down" })
swipe({ direction: "left" })

# 3. Run Maestro flows
run_maestro_flow({ flow_yaml: "- assertVisible: Welcome" })
check_maestro_flow_syntax({ flow_yaml: "- tap: Login" })

# 4. Reload app after code changes
reload_app()

# 5. Check logs if needed
get_logs({ level: "error" })

# 6. Stop session when done
stop_session()

Características del plugin

Cuando se instala como plugin de Claude Code, obtienes estas características adicionales:

Agente de QA

Delega las pruebas de QA móvil al agente qa. Prueba sistemáticamente tu aplicación en un simulador/emulador con requisitos estrictos de evidencia; sin veredictos basados solo en revisión de código.

# In Claude Code, delegate to the QA agent:
"Test the login flow on iOS simulator"  →  delegates to qa agent

El agente sigue una metodología estructurada: iniciar aplicación → inspeccionar interfaz de usuario → interactuar → verificar → informar con veredicto PASS/FAIL/INCONCLUSIVE.

Agente de escritura de flujos

El agente flow-writer inspecciona la aplicación en vivo y crea flujos de prueba YAML de Maestro:

# Ask the flow writer to create a test flow:
"Write a Maestro flow for the onboarding sequence"  →  delegates to flow-writer agent

Valida la sintaxis, ejecuta el flujo para verificar que funciona y escribe el archivo .yaml en tu proyecto.

Guía de uso

Accede a la referencia de herramientas y mejores prácticas con /expo-guide:

/expo-guide                    # Full guide
/expo-guide session            # Session lifecycle
/expo-guide debugging          # Debugging tips

Herramientas

Herramientas de ciclo de vida

Opciones de start_session

Herramientas de Maestro

Todas las herramientas de Maestro funcionan automáticamente una vez que una sesión está activa; el device_id se inyecta desde la sesión:

Nota: Las herramientas de dispositivo requieren una sesión activa. Llama a start_session primero. list_devices y check_maestro_flow_syntax pueden llamarse en cualquier momento.

Sistema de arrendamiento de dispositivos

El arrendamiento de dispositivos evita que una instancia de MCP retenga un dispositivo indefinidamente:

1. Adquirir: start_session adquiere un arrendamiento de dispositivo de 2 minutos

2. Renovación automática: Cada llamada a la herramienta de dispositivo (take_screenshot, tap_on, etc.) reinicia el temporizador de 2 minutos

3. Expirar: Si no se llama a ninguna herramienta de dispositivo durante 2 minutos, el arrendamiento expira y el dispositivo queda disponible

4. Re-adquirir: Llama a start_session de nuevo para re-adquirir (el servidor permanece en ejecución, no se necesita reinicio)

5. Verificar: get_session_status muestra el tiempo de arrendamiento restante

Varias instancias de MCP se coordinan a través de un registro basado en archivos (/tmp/expo-mcp/instances/), por lo que dos instancias no pueden reclamar el mismo dispositivo simultáneamente.

Variables de entorno

Cómo funciona

1. Inicio de sesión: start_session inicia el servidor de desarrollo de Expo, espera la conexión del dispositivo y adquiere un arrendamiento

2. Vinculación de dispositivo: El ID del dispositivo conectado se almacena en la sesión con un TTL de 2 minutos

3. Inyección automática: Todas las herramientas de dispositivo de Maestro usan automáticamente el ID de dispositivo de la sesión

4. Renovación de arrendamiento: Cada llamada a la herramienta de dispositivo reinicia el temporizador de arrendamiento

5. Fin de sesión: stop_session limpia todo, o el arrendamiento expira tras la inactividad

Entornos no interactivos (CI/CD, Agentes de IA)

Este servidor MCP habilita automáticamente el modo --offline cuando se ejecuta en entornos CI (CI=1). Esto permite que la aplicación funcione sin requerir un EXPO_TOKEN.

Qué hace el modo sin conexión

• Omite la comunicación con el servidor de Expo (firma de manifiesto)

• NO afecta las características de red de tu aplicación (llamadas API, fetch, etc.)

• El modo túnel (--tunnel) no está disponible en modo sin conexión

Si necesitas características de cuenta de Expo

Para características que requieren autenticación de Expo, desactiva el modo sin conexión y proporciona EXPO_TOKEN:

{
  "mcpServers": {
    "expo": {
      "env": {
        "EXPO_TOKEN": "your-token-here"
      }
    }
  }
}

Luego llama a start_session con offline: false:

start_session({ target: "ios-simulator", offline: false })

Requisitos

• Node.js >= 18

• Xcode (para simulador de iOS)

• Android Studio (para emulador de Android)

• Maestro CLI (para automatización de interfaz de usuario)

Licencia

MIT