iOS Simulator MCP Server

Un servidor del Protocolo de Contexto de Modelo (MCP) para interactuar con simuladores de iOS. Este servidor permite interactuar con simuladores de iOS obteniendo información sobre ellos, controlando interacciones de la interfaz de usuario e inspeccionando elementos de la interfaz.

GitHub

2.2k

Prueba este MCPPatrocinado

Documentación

iOS Simulator MCP Server

Un servidor de Protocolo de Contexto de Modelo (MCP) para interactuar con simuladores de iOS. Este servidor te permite interactuar con simuladores de iOS obteniendo información sobre ellos, controlando interacciones de UI e inspeccionando elementos de UI.

Aviso de Seguridad: Las vulnerabilidades de inyección de comandos presentes en versiones < 1.3.3 han sido corregidas. Por favor, actualiza a v1.3.3 o posterior. Consulta SECURITY.md para más detalles.

https://github.com/user-attachments/assets/a88e449c-8f1d-46a5-9816-0f97e071c460

🌟 Destacado en

Este proyecto ha sido destacado y mencionado en diversas publicaciones y recursos:

Artículo sobre Mejores Prácticas de Claude Code - Blog de ingeniería de Anthropic mostrando mejores prácticas
React Native Newsletter Número 187 - Destacado en el boletín comunitario de React Native más popular
Mobile Automation Newsletter - #56 - Destacado en un boletín de larga trayectoria sobre recursos de pruebas y automatización móvil
Listado punkeye/awesome-mcp-server - Listado en una de las colecciones curadas de servidores MCP más populares

Herramientas

`get_booted_sim_id`

Descripción: Obtiene el ID del simulador de iOS actualmente iniciado

Parámetros: Sin parámetros

`open_simulator`

Descripción: Abre la aplicación del Simulador de iOS

Parámetros: Sin parámetros

`ui_describe_all`

Descripción: Describe la información de accesibilidad de toda la pantalla en el Simulador de iOS

Parámetros:

{
  /**
   * Udid of target, can also be set with the IDB_UDID env var
   * Format: UUID (8-4-4-4-12 hexadecimal characters)
   */
  udid?: string;
}

`ui_tap`

Descripción: Toca la pantalla en el Simulador de iOS

Parámetros:

{
  /**
   * Press duration in seconds (decimal numbers allowed)
   */
  duration?: string;
  /**
   * Udid of target, can also be set with the IDB_UDID env var
   * Format: UUID (8-4-4-4-12 hexadecimal characters)
   */
  udid?: string;
  /** The x-coordinate */
  x: number;
  /** The y-coordinate */
  y: number;
}

`ui_type`

Descripción: Ingresa texto en el Simulador de iOS

Parámetros:

{
  /**
   * Udid of target, can also be set with the IDB_UDID env var
   * Format: UUID (8-4-4-4-12 hexadecimal characters)
   */
  udid?: string;
  /**
   * Text to input
   * Format: ASCII printable characters only
   */
  text: string;
}

`ui_swipe`

Descripción: Desliza en la pantalla del Simulador de iOS

Parámetros:

{
  /**
   * Swipe duration in seconds (decimal numbers allowed)
   */
  duration?: string;
  /**
   * Udid of target, can also be set with the IDB_UDID env var
   * Format: UUID (8-4-4-4-12 hexadecimal characters)
   */
  udid?: string;
  /** The starting x-coordinate */
  x_start: number;
  /** The starting y-coordinate */
  y_start: number;
  /** The ending x-coordinate */
  x_end: number;
  /** The ending y-coordinate */
  y_end: number;
  /** The size of each step in the swipe (default is 1) */
  delta?: number;
}

`ui_describe_point`

Descripción: Devuelve el elemento de accesibilidad en las coordenadas dadas en la pantalla del Simulador de iOS

Parámetros:

{
  /**
   * Udid of target, can also be set with the IDB_UDID env var
   * Format: UUID (8-4-4-4-12 hexadecimal characters)
   */
  udid?: string;
  /** The x-coordinate */
  x: number;
  /** The y-coordinate */
  y: number;
}

`ui_find_element`

Descripción: Busca en el árbol de accesibilidad y devuelve elementos que coinciden con los criterios dados

Parámetros:

{
  /** Array of search strings. An element matches if ANY string matches against its AXLabel or AXUniqueId */
  search: string[];
  /** Filter by element type (e.g. 'Button', 'StaticText', 'Group'). Case-insensitive exact match */
  type?: string;
  /** Match mode: 'substring' (default) or 'exact' */
  matchMode?: "substring" | "exact";
  /** Whether search matching is case-sensitive (default: false) */
  caseSensitive?: boolean;
  /**
   * Udid of target, can also be set with the IDB_UDID env var
   * Format: UUID (8-4-4-4-12 hexadecimal characters)
   */
  udid?: string;
}

`ui_view`

Descripción: Obtiene el contenido de imagen de una captura de pantalla comprimida de la vista actual del simulador

Parámetros:

{
  /**
   * Udid of target, can also be set with the IDB_UDID env var
   * Format: UUID (8-4-4-4-12 hexadecimal characters)
   */
  udid?: string;
}

`screenshot`

Descripción: Toma una captura de pantalla del Simulador de iOS

Parámetros:

{
  /**
   * Udid of target, can also be set with the IDB_UDID env var
   * Format: UUID (8-4-4-4-12 hexadecimal characters)
   */
  udid?: string;
  /** File path where the screenshot will be saved. If relative, it uses the directory specified by the `IOS_SIMULATOR_MCP_DEFAULT_OUTPUT_DIR` env var, or `~/Downloads` if not set. */
  output_path: string;
  /** Image format (png, tiff, bmp, gif, or jpeg). Default is png. */
  type?: "png" | "tiff" | "bmp" | "gif" | "jpeg";
  /** Display to capture (internal or external). Default depends on device type. */
  display?: "internal" | "external";
  /** For non-rectangular displays, handle the mask by policy (ignored, alpha, or black) */
  mask?: "ignored" | "alpha" | "black";
}

`record_video`

Descripción: Graba un video del Simulador de iOS usando simctl directamente

Parámetros:

{
  /**
   * Udid of target, can also be set with the IDB_UDID env var
   * Format: UUID (8-4-4-4-12 hexadecimal characters)
   */
  udid?: string;
  /** Optional output path. If not provided, a default name will be used. The file will be saved in the directory specified by `IOS_SIMULATOR_MCP_DEFAULT_OUTPUT_DIR` or in `~/Downloads` if the environment variable is not set. */
  output_path?: string;
  /** Specifies the codec type: "h264" or "hevc". Default is "hevc". */
  codec?: "h264" | "hevc";
  /** Display to capture: "internal" or "external". Default depends on device type. */
  display?: "internal" | "external";
  /** For non-rectangular displays, handle the mask by policy: "ignored", "alpha", or "black". */
  mask?: "ignored" | "alpha" | "black";
  /** Force the output file to be written to, even if the file already exists. */
  force?: boolean;
}

`stop_recording`

Descripción: Detiene la grabación de video del simulador usando killall

Parámetros: Sin parámetros

`install_app`

Descripción: Instala un paquete de aplicación (.app o .ipa) en el Simulador de iOS

Parámetros:

{
  /**
   * Udid of target, can also be set with the IDB_UDID env var
   * Format: UUID (8-4-4-4-12 hexadecimal characters)
   */
  udid?: string;
  /** Path to the app bundle (.app directory or .ipa file) to install */
  app_path: string;
}

`launch_app`

Descripción: Inicia una aplicación en el Simulador de iOS por identificador de paquete

Parámetros:

{
  /**
   * Udid of target, can also be set with the IDB_UDID env var
   * Format: UUID (8-4-4-4-12 hexadecimal characters)
   */
  udid?: string;
  /** Bundle identifier of the app to launch (e.g., com.apple.mobilesafari) */
  bundle_id: string;
  /** Terminate the app if it is already running before launching */
  terminate_running?: boolean;
  /** Optional environment variables passed via SIMCTL_CHILD_ to simctl launch */
  env?: Record<string, string>;
}

Notas: Las variables de entorno se pasan usando SIMCTL_CHILD_ porque simctl launch no admite --env/--envs en todas las versiones de Xcode.

Ejemplo:

{
  "bundle_id": "com.example.app",
  "terminate_running": true,
  "env": {
    "FOO": "bar",
    "BAZ": "qux"
  }
}

`terminate_app`

Descripción: Termina una aplicación en ejecución en el Simulador de iOS por identificador de paquete. Útil para probar flujos de inicio en frío y verificar la recuperación de fallos sin reinstalar la aplicación.

Parámetros:

{
  /**
   * Udid of target, can also be set with the IDB_UDID env var
   * Format: UUID (8-4-4-4-12 hexadecimal characters)
   */
  udid?: string;
  /** Bundle identifier of the app to terminate (e.g., com.apple.mobilesafari) */
  bundle_id: string;
}

`open_url`

Descripción: Abre una URL o enlace profundo en el Simulador de iOS. Maneja URLs https:// (a través de Safari), esquemas de URL personalizados y enlaces universales — esencial para probar el enrutamiento de enlaces profundos y flujos de redirección OAuth.

Parámetros:

{
  /**
   * Udid of target, can also be set with the IDB_UDID env var
   * Format: UUID (8-4-4-4-12 hexadecimal characters)
   */
  udid?: string;
  /** The URL or deep link to open (e.g., https://example.com or myapp://screen/detail) */
  url: string;
}

`list_apps`

Descripción: Lista todas las aplicaciones instaladas en el Simulador de iOS con sus identificadores de paquete y nombres de visualización, ordenados alfabéticamente. Elimina la necesidad de buscar identificadores de paquete manualmente antes de llamar a launch_app o terminate_app.

Parámetros:

{
  /**
   * Udid of target, can also be set with the IDB_UDID env var
   * Format: UUID (8-4-4-4-12 hexadecimal characters)
   */
  udid?: string;
}

💡 Caso de Uso: Paso de QA mediante Llamadas a Herramientas MCP

Este servidor MCP permite a los asistentes de IA integrados con un cliente de Protocolo de Contexto de Modelo (MCP) realizar tareas de Aseguramiento de Calidad mediante llamadas a herramientas. Esto es útil inmediatamente después de implementar funciones para ayudar a garantizar la consistencia de la UI y el comportamiento correcto.

Cómo Usar

Después de una implementación de función, instruye a tu asistente de IA dentro de su entorno de cliente MCP para que use las herramientas disponibles. Por ejemplo, en el modo agente de Cursor, podrías usar los siguientes mensajes para validar y documentar rápidamente las interacciones de UI.

Ejemplos de Mensajes

Verificar Elementos de UI:

Verify all accessibility elements on the current screen

Confirmar Entrada de Texto:

Enter "QA Test" into the text input field and confirm the input is correct

Comprobar Respuesta al Toque:

Tap on coordinates x=250, y=400 and verify the expected element is triggered

Validar Acción de Deslizamiento:

Swipe from x=150, y=600 to x=150, y=100 and confirm correct behavior

Verificación Detallada de Elementos:

Describe the UI element at position x=300, y=350 to ensure proper labeling and functionality

Mostrar la Pantalla del Simulador a tu Agente de IA:
```
View the current simulator screen
```

Tomar Captura de Pantalla:

Take a screenshot of the current simulator screen and save it to my_screenshot.png

Grabar Video:

Start recording a video of the simulator screen (saves to the default output directory, which is `~/Downloads` unless overridden by `IOS_SIMULATOR_MCP_DEFAULT_OUTPUT_DIR`)

Detener Grabación:

Stop the current simulator screen recording

Instalar Aplicación:

Install the app at path/to/MyApp.app on the simulator

Iniciar Aplicación:

Launch the Safari app (com.apple.mobilesafari) on the simulator

🧭 Consejo: Enlace Profundo Directo a una Pantalla

Los agentes pueden perder muchas iteraciones tocando y deslizando su camino hacia una ruta profundamente anidada. Cuando tu aplicación registra un esquema de URL (o Enlace Universal), generalmente es más rápido saltar directamente a la pantalla objetivo en lugar de navegar paso a paso.

Puedes abrir un enlace profundo con uri-scheme:

npx uri-scheme open "myapp://products/42" --ios

Esto apunta al simulador actualmente iniciado. Internamente, es equivalente a:

xcrun simctl openurl booted "myapp://products/42"

Ambos funcionan para esquemas personalizados (myapp://...) y URLs web (https://..., que activan Enlaces Universales si tu aplicación está configurada para ellos).

Ejemplo de mensaje:

Open the deep link myapp://products/42 in the simulator, then verify the product
details screen is shown

Usa esto para acortar los bucles del agente: enlaza profundamente a la pantalla bajo prueba, luego usa las herramientas de UI (ui_describe_all, ui_tap, ui_view, …) para validarla.

Requisitos Previos

Node.js 20 o posterior
macOS (ya que los simuladores de iOS solo están disponibles en macOS)
Xcode y simuladores de iOS instalados
Herramienta IDB de Facebook (consulta la guía de instalación)

Instalación

Esta sección proporciona instrucciones para integrar el servidor MCP del Simulador de iOS con diferentes clientes de Protocolo de Contexto de Modelo (MCP).

Instalación con Cursor

Cursor gestiona los servidores MCP a través de su archivo de configuración ubicado en ~/.cursor/mcp.json.

Opción 1: Usando NPX (Recomendado)

Edita tu archivo de configuración MCP de Cursor. A menudo puedes abrirlo directamente desde Cursor o usar un comando como:

# Open with your default editor (or use 'code', 'vim', etc.)
open ~/.cursor/mcp.json
# Or use Cursor's command if available
# cursor ~/.cursor/mcp.json

Agrega o actualiza la sección mcpServers con la configuración del servidor del simulador de iOS:

{
  "mcpServers": {
    // ... other servers might be listed here ...
    "ios-simulator": {
      "command": "npx",
      "args": ["-y", "ios-simulator-mcp"]
    }
  }
}

Asegúrate de que la estructura JSON sea válida, especialmente si mcpServers ya existe.

Si prefieres pnpm, usa su ejecutor dlx en su lugar:

{
  "mcpServers": {
    "ios-simulator": {
      "command": "pnpm",
      "args": ["dlx", "ios-simulator-mcp"]
    }
  }
}

Reinicia Cursor para que los cambios surtan efecto.

Opción 2: Desarrollo Local

Clona este repositorio:

git clone https://github.com/joshuayoes/ios-simulator-mcp
cd ios-simulator-mcp

Instala las dependencias (npm es el predeterminado; pnpm también es compatible):

npm install
# or, using pnpm (installs from the committed pnpm-lock.yaml):
pnpm install

Compila el proyecto:
```
npm run build
# or:
pnpm run build
```
Edita tu archivo de configuración MCP de Cursor (como se muestra en la Opción 1).

Agrega o actualiza la sección mcpServers, apuntando a tu compilación local:

{
  "mcpServers": {
    // ... other servers might be listed here ...
    "ios-simulator": {
      "command": "node",
      "args": ["/full/path/to/your/ios-simulator-mcp/build/index.js"]
    }
  }
}

Importante: Reemplaza /full/path/to/your/ con la ruta absoluta donde clonaste el repositorio de ios-simulator-mcp.

Reinicia Cursor para que los cambios surtan efecto.

Instalación con Claude Code

La CLI de Claude Code puede gestionar servidores MCP usando los comandos claude mcp o editando sus archivos de configuración directamente. Para más detalles sobre la configuración MCP de Claude Code, consulta la documentación oficial.

Opción 1: Usando NPX (Recomendado)

Agrega el servidor usando el comando claude mcp add:

claude mcp add ios-simulator npx ios-simulator-mcp
# or, with pnpm:
claude mcp add ios-simulator -- pnpm dlx ios-simulator-mcp

Reinicia cualquier sesión de Claude Code en ejecución si es necesario.

Opción 2: Desarrollo Local

Clona este repositorio, instala las dependencias y compila el proyecto como se describe en los pasos 1-3 de "Desarrollo Local" de Cursor.
Agrega el servidor usando el comando claude mcp add, apuntando a tu compilación local:
```
claude mcp add ios-simulator -- node "/full/path/to/your/ios-simulator-mcp/build/index.js"
```
Importante: Reemplaza /full/path/to/your/ con la ruta absoluta donde clonaste el repositorio de ios-simulator-mcp.
Reinicia cualquier sesión de Claude Code en ejecución si es necesario.

Configuración

Variables de Entorno

Variable	Descripción	Ejemplo
`IOS_SIMULATOR_MCP_FILTERED_TOOLS`	Una lista separada por comas de nombres de herramientas para filtrar y no registrar.	`screenshot,record_video,stop_recording`
`IOS_SIMULATOR_MCP_DEFAULT_OUTPUT_DIR`	Especifica un directorio predeterminado para archivos de salida como capturas de pantalla y grabaciones de video. Si no se establece, se usará `~/Downloads`. Esto puede ser útil si tu agente tiene acceso limitado al sistema de archivos.	`~/Code/awesome-project/tmp`
`IOS_SIMULATOR_MCP_IDB_PATH`	Especifica una ruta personalizada al ejecutable de IDB. Si no se establece, se usará `idb` (asumiendo que está en tu PATH). Útil si IDB está instalado en una ubicación no estándar.	`~/bin/idb` o `/usr/local/bin/idb`

Ejemplo de Configuración

{
  "mcpServers": {
    "ios-simulator": {
      "command": "npx",
      "args": ["-y", "ios-simulator-mcp"],
      "env": {
        "IOS_SIMULATOR_MCP_FILTERED_TOOLS": "screenshot,record_video,stop_recording",
        "IOS_SIMULATOR_MCP_DEFAULT_OUTPUT_DIR": "~/Code/awesome-project/tmp",
        "IOS_SIMULATOR_MCP_IDB_PATH": "~/bin/idb"
      }
    }
  }
}

Listados de Servidores en el Registro MCP

Licencia

MIT