Servidor MCP para el Simulador de iOS

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

Aviso de seguridad: Se han corregido las vulnerabilidades de inyección de comandos presentes en versiones anteriores a la 1.3.3. Por favor, actualice a la versión 1.3.3 o posterior. Consulte SECURITY.md para más detalles.

https://github.com/user-attachments/assets/453ebe7b-cc93-4ac2-b08d-0f8ac8339ad3

🌟 Destacado en

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

• Artículo de mejores prácticas de Claude Code - Blog de ingeniería de Anthropic que muestra las mejores prácticas

• React Native Newsletter Issue 187 - Destacado en el boletín informativo más popular de la comunidad de React Native

• Mobile Automation Newsletter - #56 - Destacado en un boletín de larga trayectoria sobre pruebas móviles y recursos de automatización

• Listado en punkeye/awesome-mcp-server - Incluido en una de las colecciones más populares de servidores MCP seleccionados

Related MCP server: iOS Device Control MCP Server

Herramientas

get_booted_sim_id

Descripción: Obtiene el ID del simulador de iOS que se está ejecutando actualmente

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: Introduce 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 el dedo por la pantalla en el 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 indicadas 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 los 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 la 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 vídeo 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 vídeo 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 mediante el identificador del 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"
  }
}

💡 Caso de uso: Paso de QA mediante llamadas a herramientas MCP

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

Cómo utilizarlo

Después de implementar una función, indique a su asistente de IA dentro de su entorno de cliente MCP que utilice las herramientas disponibles. Por ejemplo, en el modo agente de Cursor, podría usar las siguientes instrucciones para validar y documentar rápidamente las interacciones de la interfaz de usuario.

Ejemplos de instrucciones

• Verificar elementos de la interfaz:

  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

• Comprobació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 su 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 vídeo:

  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

Requisitos previos

• Node.js

• macOS (ya que los simuladores de iOS solo están disponibles en macOS)

• Xcode y simuladores de iOS instalados

• Herramienta IDB de Facebook (ver guía de instalación)

Instalación

Esta sección proporciona instrucciones para integrar el servidor MCP del Simulador de iOS con diferentes clientes del 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)

1. Edite su archivo de configuración MCP de Cursor. A menudo puede 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

2. Añada o actualice 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úrese de que la estructura JSON sea válida, especialmente si mcpServers ya existe.

3. Reinicie Cursor para que los cambios surtan efecto.

Opción 2: Desarrollo local

1. Clone este repositorio:

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

2. Instale las dependencias:

   npm install

3. Compile el proyecto:

   npm run build

4. Edite su archivo de configuración MCP de Cursor (como se muestra en la Opción 1).

5. Añada o actualice la sección mcpServers, apuntando a su 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: Reemplace /full/path/to/your/ con la ruta absoluta a donde clonó el repositorio ios-simulator-mcp.

6. Reinicie 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 obtener más detalles sobre la configuración de MCP en Claude Code, consulte la documentación oficial.

Opción 1: Usando NPX (Recomendado)

1. Añada el servidor usando el comando claude mcp add:

   claude mcp add ios-simulator npx ios-simulator-mcp

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

Opción 2: Desarrollo local

1. Clone este repositorio, instale las dependencias y compile el proyecto como se describe en los pasos 1-3 de "Desarrollo local" de Cursor.

2. Añada el servidor usando el comando claude mcp add, apuntando a su compilación local:

   claude mcp add ios-simulator -- node "/full/path/to/your/ios-simulator-mcp/build/index.js"

   Importante: Reemplace /full/path/to/your/ con la ruta absoluta a donde clonó el repositorio ios-simulator-mcp.

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

Configuración

Variables de entorno

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 del registro de servidores MCP

Licencia

MIT