phantom-mcp

Servidor MCP que permite a Claude Code ver y controlar simuladores de iOS, emuladores de Android y dispositivos reales. 24 herramientas para probar aplicaciones móviles sin salir de la terminal.

Claude puede tomar capturas de pantalla, leer la pantalla, tocar, desplazarse, rellenar campos, verificar aserciones, grabar videos — automáticamente, en iOS y Android.

Se genera automáticamente un informe de prueba con capturas de pantalla en cada sesión de prueba.

Arquitectura

Claude Code
    | MCP protocol (stdio)
    v
Phantom (Node.js TypeScript)
    |                       |
    v                       v
iOS                      Android
  xcrun simctl             ADB
  WebDriverAgent           UIAutomator
  (localhost:8100)         (adb shell)
    |                       |
    v                       v
Simulateur / iPhone    Emulateur / Device

Related MCP server: mobile-device-mcp

Requisitos previos

Instalación

Opción A — npm (recomendado)

# 1. Installer le package
npm install -g phantom-mcp

# 2. Installer Appium + driver iOS
npm install -g appium
appium driver install xcuitest

# 3. Enregistrer dans Claude Code
claude mcp add -s user phantom -- npx phantom-mcp

Opción B — desde las fuentes

git clone https://github.com/nthimpulse/phantom-mcp.git
cd phantom-mcp
npm install
npm run build
claude mcp add -s user phantom -- node "$(pwd)/build/index.js"

Las 24 herramientas

Gestión de dispositivos

Observación

Aserciones

Interacción

Navegación

Acciones del dispositivo

Ciclo de vida de la aplicación

Análisis y Automatización (Nivel 3)

Funcionamiento automático

Selección de dispositivo

Phantom nunca arranca un dispositivo automáticamente. Te pide que elijas:

1. Si solo hay 1 dispositivo activo, lo usa automáticamente

2. Si hay varios, te pide que elijas con set_device

3. Si no hay ninguno, te muestra la lista de dispositivos disponibles

Auto-lanzamiento de WDA (iOS)

WebDriverAgent se lanza automáticamente con la primera herramienta de iOS que lo necesite. El primer lanzamiento tarda ~60-90s (compilación de Xcode), luego es instantáneo.

ADB multidispositivo (Android)

Todos los comandos ADB se dirigen al dispositivo seleccionado mediante -s <serial>. Sin confusión multidispositivo.

Entrada de texto (compatible con AZERTY)

La entrada utiliza pbcopy + Cmd+V (pegar) en lugar del teclado virtual. Es instantáneo y funciona en todas las distribuciones de teclado (AZERTY, QWERTY, etc.).

Informe de prueba automático

Cada acción (tocar, escribir, deslizar, afirmar...) se registra automáticamente con una captura de pantalla. Al final de la prueba, se genera un informe markdown en /tmp/phantom-report-xxx/.

Seguridad

• Todos los comandos del sistema pasan por execFile (sin shell)

• Entradas validadas por regex: IDs de paquete, UDIDs, nombres de paquete, nombres de AVD, URLs

• Predicados de iOS escapados (anti-inyección)

• Texto de Android escapado para el shell del dispositivo

• Cero as any, cero exec() shell

Configuración

Variables de entorno opcionales:

• PHANTOM_WDA_PATH — ruta hacia WebDriverAgent (predeterminado: ~/.appium/...)

• PHANTOM_WDA_URL — URL de WDA (predeterminado: http://localhost:8100)

Contribuir

Ver CONTRIBUTING.md para la configuración local, el patrón para añadir una nueva herramienta, las convenciones de nomenclatura y el flujo de trabajo de PR.

Ver también:

• docs/LIMITATIONS.md — limitaciones conocidas + soluciones alternativas

• docs/PATTERNS.md — recetas prácticas (DatePicker iOS, hojas inferiores, etc.)

• docs/FEATURE_REQUESTS.md — características priorizadas para las próximas versiones

• docs/CHANGES_2026-04-30.md — notas de la versión v2.3.0

Solución de problemas

WDA se bloquea en bucle

MobAI u otra herramienta está utilizando el puerto 8100.

lsof -i :8100
pkill -f "MobAI"

"Ningún dispositivo disponible"

xcrun simctl list devices available   # iOS
adb devices -l                        # Android

WDA no arranca

cd ~/.appium/node_modules/appium-xcuitest-driver/node_modules/appium-webdriveragent
xcodebuild -project WebDriverAgent.xcodeproj \
  -scheme WebDriverAgentRunner \
  -destination "platform=iOS Simulator,name=iPhone 17 Pro" \
  test

ADB no encontrado

ls ~/Library/Android/sdk/platform-tools/adb

Estructura del proyecto

phantom/
  src/
    index.ts                Point d'entree MCP (24 tools)
    platforms/
      types.ts              Interfaces communes
      ios/
        simctl.ts            Wrapper xcrun simctl
        wda.ts               Client WDA + auto-launch
      android/
        adb.ts               Wrapper ADB complet
    tools/                   24 tools (21 fichiers)
    utils/
      device-manager.ts      Detection + routing multi-device
      xml.ts                 Parser XML partage
  docs/
    README.md               Ce fichier
    TUTORIAL.md             Tuto pas-a-pas
    FLOWS.md                Exemples de flows de test