MCP-сервер для симулятора iOS

Сервер протокола контекста модели (MCP) для взаимодействия с симуляторами iOS. Этот сервер позволяет вам взаимодействовать с симуляторами iOS, получая информацию о них, управляя взаимодействиями с UI и проверяя элементы интерфейса.

Уведомление о безопасности: Уязвимости внедрения команд, присутствовавшие в версиях < 1.3.3, были исправлены. Пожалуйста, обновитесь до версии 1.3.3 или более поздней. Подробности см. в SECURITY.md.

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

🌟 Где упоминался

Этот проект был представлен и упомянут в различных публикациях и ресурсах:

• Статья о лучших практиках Claude Code — инженерный блог Anthropic, демонстрирующий лучшие практики

• React Native Newsletter, выпуск 187 — представлен в самом популярном новостном бюллетене сообщества React Native

• Mobile Automation Newsletter — #56 — долгоживущий новостной бюллетень о ресурсах для мобильного тестирования и автоматизации

• Список punkeye/awesome-mcp-server — включен в одну из самых популярных коллекций курируемых MCP-серверов

Related MCP server: iOS Device Control MCP Server

Инструменты

get_booted_sim_id

Описание: Получение ID запущенного в данный момент симулятора iOS

Параметры: Нет параметров

open_simulator

Описание: Открывает приложение iOS Simulator

Параметры: Нет параметров

ui_describe_all

Описание: Описывает информацию о доступности (accessibility) для всего экрана в симуляторе iOS

Параметры:

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

Описание: Нажатие на экран в симуляторе iOS

Параметры:

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

Описание: Ввод текста в симулятор iOS

Параметры:

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

Описание: Свайп по экрану в симуляторе iOS

Параметры:

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

Описание: Возвращает элемент доступности по заданным координатам на экране симулятора iOS

Параметры:

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

Описание: Выполняет поиск по дереву доступности и возвращает элементы, соответствующие заданным критериям

Параметры:

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

Описание: Получение содержимого изображения сжатого скриншота текущего вида симулятора

Параметры:

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

Описание: Делает скриншот симулятора iOS

Параметры:

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

Описание: Записывает видео симулятора iOS, используя напрямую simctl

Параметры:

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

Описание: Останавливает запись видео симулятора с помощью killall

Параметры: Нет параметров

install_app

Описание: Устанавливает пакет приложения (.app или .ipa) на симулятор iOS

Параметры:

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

Описание: Запускает приложение на симуляторе iOS по идентификатору пакета (bundle identifier)

Параметры:

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

Примечания: Переменные окружения передаются с использованием SIMCTL_CHILD_, так как simctl launch не поддерживает --env/--envs во всех версиях Xcode.

Пример:

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

💡 Вариант использования: Этап QA через вызовы инструментов MCP

Этот MCP-сервер позволяет ИИ-ассистентам, интегрированным с клиентом протокола контекста модели (MCP), выполнять задачи по обеспечению качества (QA) путем вызова инструментов. Это полезно сразу после реализации функций, чтобы помочь обеспечить согласованность пользовательского интерфейса и правильность поведения.

Как использовать

После реализации функции дайте указание вашему ИИ-ассистенту в среде клиента MCP использовать доступные инструменты. Например, в режиме агента Cursor вы можете использовать приведенные ниже подсказки для быстрой проверки и документирования взаимодействий с UI.

Примеры подсказок

• Проверка элементов UI:

  Verify all accessibility elements on the current screen

• Подтверждение ввода текста:

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

• Проверка отклика на нажатие:

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

• Проверка действия свайпа:

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

• Детальная проверка элемента:

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

• Показать вашему ИИ-агенту экран симулятора:

  View the current simulator screen

• Сделать скриншот:

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

• Записать видео:

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

• Остановить запись:

  Stop the current simulator screen recording

• Установить приложение:

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

• Запустить приложение:

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

Предварительные требования

• Node.js

• macOS (поскольку симуляторы iOS доступны только на macOS)

• Установленные Xcode и симуляторы iOS

• Инструмент Facebook IDB (см. руководство по установке)

Установка

В этом разделе приведены инструкции по интеграции MCP-сервера симулятора iOS с различными клиентами протокола контекста модели (MCP).

Установка с Cursor

Cursor управляет MCP-серверами через файл конфигурации, расположенный по адресу ~/.cursor/mcp.json.

Вариант 1: Использование NPX (рекомендуется)

1. Отредактируйте файл конфигурации MCP в Cursor. Часто его можно открыть напрямую из Cursor или использовать команду:

   # 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. Добавьте или обновите раздел mcpServers конфигурацией сервера симулятора iOS:

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

   Убедитесь, что структура JSON корректна, особенно если раздел mcpServers уже существует.

3. Перезапустите Cursor, чтобы изменения вступили в силу.

Вариант 2: Локальная разработка

1. Клонируйте этот репозиторий:

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

2. Установите зависимости:

   npm install

3. Соберите проект:

   npm run build

4. Отредактируйте файл конфигурации MCP в Cursor (как показано в Варианте 1).

5. Добавьте или обновите раздел mcpServers, указав путь к вашей локальной сборке:

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

   Важно: Замените /full/path/to/your/ на абсолютный путь к месту, куда вы клонировали репозиторий ios-simulator-mcp.

6. Перезапустите Cursor, чтобы изменения вступили в силу.

Установка с Claude Code

CLI Claude Code может управлять MCP-серверами с помощью команд claude mcp или путем прямого редактирования файлов конфигурации. Для получения дополнительной информации о настройке MCP в Claude Code обратитесь к официальной документации.

Вариант 1: Использование NPX (рекомендуется)

1. Добавьте сервер с помощью команды claude mcp add:

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

2. При необходимости перезапустите все запущенные сессии Claude Code.

Вариант 2: Локальная разработка

1. Клонируйте этот репозиторий, установите зависимости и соберите проект, как описано в шагах 1-3 раздела "Локальная разработка" для Cursor.

2. Добавьте сервер с помощью команды claude mcp add, указав путь к вашей локальной сборке:

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

   Важно: Замените /full/path/to/your/ на абсолютный путь к месту, куда вы клонировали репозиторий ios-simulator-mcp.

3. При необходимости перезапустите все запущенные сессии Claude Code.

Конфигурация

Переменные окружения

Пример конфигурации

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

Лицензия

MIT