iOS Simulator MCP Server

Ein Model Context Protocol (MCP) Server für die Interaktion mit iOS-Simulatoren. Dieser Server ermöglicht es Ihnen, mit iOS-Simulatoren zu interagieren, indem Sie Informationen über sie abrufen, UI-Interaktionen steuern und UI-Elemente untersuchen.

Sicherheitshinweis: Befehlsinjektionsschwachstellen in Versionen < 1.3.3 wurden behoben. Bitte aktualisieren Sie auf v1.3.3 oder höher. Siehe SECURITY.md für Details.

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

🌟 Vorgestellt in

Dieses Projekt wurde in verschiedenen Publikationen und Ressourcen vorgestellt und erwähnt:

• Claude Code Best Practices Artikel - Anthropics Engineering-Blog, der Best Practices vorstellt

• React Native Newsletter Ausgabe 187 - Vorgestellt im populärsten Newsletter der React Native-Community

• Mobile Automation Newsletter - #56 - Vorgestellt in einem langjährigen Newsletter über mobile Test- und Automatisierungsressourcen

• punkeye/awesome-mcp-server Auflistung - Gelistet in einer der populärsten kuratierten Sammlungen von MCP-Servern

Related MCP server: iOS Device Control MCP Server

Tools

get_booted_sim_id

Beschreibung: Ruft die ID des aktuell gestarteten iOS-Simulators ab

Parameter: Keine Parameter

open_simulator

Beschreibung: Öffnet die iOS Simulator-Anwendung

Parameter: Keine Parameter

ui_describe_all

Beschreibung: Beschreibt Barrierefreiheitsinformationen für den gesamten Bildschirm im iOS-Simulator

Parameter:

{
  /**
   * 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

Beschreibung: Tippen auf den Bildschirm im iOS-Simulator

Parameter:

{
  /**
   * 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

Beschreibung: Eingabe von Text in den iOS-Simulator

Parameter:

{
  /**
   * 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

Beschreibung: Wischen auf dem Bildschirm im iOS-Simulator

Parameter:

{
  /**
   * 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

Beschreibung: Gibt das Barrierefreiheitselement an den angegebenen Koordinaten auf dem Bildschirm des iOS-Simulators zurück

Parameter:

{
  /**
   * 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

Beschreibung: Durchsucht den Barrierefreiheitsbaum und gibt Elemente zurück, die den angegebenen Kriterien entsprechen

Parameter:

{
  /** 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

Beschreibung: Ruft den Bildinhalt eines komprimierten Screenshots der aktuellen Simulatoransicht ab

Parameter:

{
  /**
   * 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

Beschreibung: Erstellt einen Screenshot des iOS-Simulators

Parameter:

{
  /**
   * 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

Beschreibung: Zeichnet ein Video des iOS-Simulators direkt mit simctl auf

Parameter:

{
  /**
   * 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

Beschreibung: Stoppt die Videoaufnahme des Simulators mit killall

Parameter: Keine Parameter

install_app

Beschreibung: Installiert ein App-Bundle (.app oder .ipa) auf dem iOS-Simulator

Parameter:

{
  /**
   * 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

Beschreibung: Startet eine App auf dem iOS-Simulator anhand des Bundle-Identifikators

Parameter:

{
  /**
   * 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>;
}

Hinweise: Umgebungsvariablen werden mit SIMCTL_CHILD_ übergeben, da simctl launch nicht auf allen Xcode-Versionen --env/--envs unterstützt.

Beispiel:

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

💡 Anwendungsfall: QA-Schritt via MCP-Tool-Aufrufe

Dieser MCP-Server ermöglicht es KI-Assistenten, die in einen Model Context Protocol (MCP) Client integriert sind, Qualitätssicherungsaufgaben durch Tool-Aufrufe durchzuführen. Dies ist unmittelbar nach der Implementierung von Funktionen nützlich, um die UI-Konsistenz und das korrekte Verhalten sicherzustellen.

Verwendung

Weisen Sie Ihren KI-Assistenten nach der Implementierung einer Funktion innerhalb seiner MCP-Client-Umgebung an, die verfügbaren Tools zu verwenden. Im Agenten-Modus von Cursor könnten Sie beispielsweise die unten stehenden Prompts verwenden, um UI-Interaktionen schnell zu validieren und zu dokumentieren.

Beispiel-Prompts

• UI-Elemente verifizieren:

  Verify all accessibility elements on the current screen

• Texteingabe bestätigen:

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

• Tipp-Reaktion prüfen:

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

• Wischaktion validieren:

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

• Detaillierte Elementprüfung:

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

• Ihrem KI-Agenten den Simulator-Bildschirm zeigen:

  View the current simulator screen

• Screenshot erstellen:

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

• Video aufnehmen:

  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`)

• Aufnahme stoppen:

  Stop the current simulator screen recording

• App installieren:

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

• App starten:

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

Voraussetzungen

• Node.js

• macOS (da iOS-Simulatoren nur auf macOS verfügbar sind)

• Xcode und installierte iOS-Simulatoren

• Facebook IDB Tool (siehe Installationsanleitung)

Installation

Dieser Abschnitt enthält Anweisungen zur Integration des iOS Simulator MCP-Servers mit verschiedenen Model Context Protocol (MCP) Clients.

Installation mit Cursor

Cursor verwaltet MCP-Server über seine Konfigurationsdatei unter ~/.cursor/mcp.json.

Option 1: Verwendung von NPX (Empfohlen)

1. Bearbeiten Sie Ihre Cursor MCP-Konfigurationsdatei. Sie können sie oft direkt aus Cursor öffnen oder einen Befehl wie diesen verwenden:

   # 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. Fügen Sie den Abschnitt mcpServers mit der Konfiguration des iOS-Simulator-Servers hinzu oder aktualisieren Sie ihn:

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

   Stellen Sie sicher, dass die JSON-Struktur gültig ist, insbesondere wenn mcpServers bereits existiert.

3. Starten Sie Cursor neu, damit die Änderungen wirksam werden.

Option 2: Lokale Entwicklung

1. Klonen Sie dieses Repository:

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

2. Installieren Sie die Abhängigkeiten:

   npm install

3. Erstellen Sie das Projekt:

   npm run build

4. Bearbeiten Sie Ihre Cursor MCP-Konfigurationsdatei (wie in Option 1 gezeigt).

5. Fügen Sie den Abschnitt mcpServers hinzu oder aktualisieren Sie ihn, wobei Sie auf Ihren lokalen Build verweisen:

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

   Wichtig: Ersetzen Sie /full/path/to/your/ durch den absoluten Pfad zu dem Ort, an den Sie das ios-simulator-mcp Repository geklont haben.

6. Starten Sie Cursor neu, damit die Änderungen wirksam werden.

Installation mit Claude Code

Das Claude Code CLI kann MCP-Server über die claude mcp Befehle oder durch direktes Bearbeiten der Konfigurationsdateien verwalten. Weitere Details zur Claude Code MCP-Konfiguration finden Sie in der offiziellen Dokumentation.

Option 1: Verwendung von NPX (Empfohlen)

1. Fügen Sie den Server mit dem Befehl claude mcp add hinzu:

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

2. Starten Sie bei Bedarf laufende Claude Code-Sitzungen neu.

Option 2: Lokale Entwicklung

1. Klonen Sie dieses Repository, installieren Sie die Abhängigkeiten und erstellen Sie das Projekt wie in den Schritten 1-3 der Cursor "Lokale Entwicklung" beschrieben.

2. Fügen Sie den Server mit dem Befehl claude mcp add hinzu und verweisen Sie auf Ihren lokalen Build:

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

   Wichtig: Ersetzen Sie /full/path/to/your/ durch den absoluten Pfad zu dem Ort, an den Sie das ios-simulator-mcp Repository geklont haben.

3. Starten Sie bei Bedarf laufende Claude Code-Sitzungen neu.

Konfiguration

Umgebungsvariablen

Konfigurationsbeispiel

{
  "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"
      }
    }
  }
}

MCP Registry Server Auflistungen

Lizenz

MIT