Перейти к основному содержанию

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

На этой странице документированы все параметры конфигурации для сервера WebdriverIO MCP.

Конфигурация сервера MCP​

Сервер MCP настраивается через конфигурационные файлы Claude Desktop или Claude Code.

Базовая конфигурация​

macOS​

Редактируйте ~/Library/Application Support/Claude/claude_desktop_config.json:

{
    "mcpServers": {
        "wdio-mcp": {
            "command": "npx",
            "args": ["-y", "@wdio/mcp"]
        }
    }
}

Windows​

Редактируйте %APPDATA%\Claude\claude_desktop_config.json:

{
    "mcpServers": {
        "wdio-mcp": {
            "command": "npx",
            "args": ["-y", "@wdio/mcp"]
        }
    }
}

Claude Code​

Редактируйте .claude/settings.json вашего проекта:

{
    "mcpServers": {
        "wdio-mcp": {
            "command": "npx",
            "args": ["-y", "@wdio/mcp"]
        }
    }
}

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

Настройте соединение с сервером Appium и другие параметры через переменные окружения.

Соединение с Appium​

ПеременнаяТипПо умолчаниюОписание
APPIUM_URLstring127.0.0.1Хост сервера Appium
APPIUM_URL_PORTnumber4723Порт сервера Appium
APPIUM_PATHstring/Путь сервера Appium

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

{
    "mcpServers": {
        "wdio-mcp": {
            "command": "npx",
            "args": ["-y", "@wdio/mcp"],
            "env": {
                "APPIUM_URL": "192.168.1.100",
                "APPIUM_URL_PORT": "4724",
                "APPIUM_PATH": "/wd/hub"
            }
        }
    }
}

Опции сессии браузера​

Опции, доступные при запуске сессии браузера через инструмент start_browser.

headless​

  • Тип: boolean
  • Обязательно: Нет
  • По умолчанию: false

Запуск Chrome в режиме без интерфейса (без видимого окна браузера). Полезно для сред CI/CD или когда вам не нужно видеть браузер.

windowWidth​

  • Тип: number
  • Обязательно: Нет
  • По умолчанию: 1920
  • Диапазон: 400 - 3840

Начальная ширина окна браузера в пикселях.

windowHeight​

  • Тип: number
  • Обязательно: Нет
  • По умолчанию: 1080
  • Диапазон: 400 - 2160

Начальная высота окна браузера в пикселях.

  • Тип: string
  • Обязательно: Нет

URL для перехода сразу после запуска браузера. Это эффективнее, чем вызов start_browser с последующим вызовом navigate.

Пример: Запуск браузера и переход за один вызов:

Start Chrome and navigate to https://webdriver.io

Опции мобильной сессии​

Опции, доступные при запуске сессии мобильного приложения через инструмент start_app_session.

Опции платформы​

platform​

  • Тип: string
  • Обязательно: Да
  • Значения: iOS | Android

Мобильная платформа для автоматизации.

platformVersion​

  • Тип: string
  • Обязательно: Нет

Версия ОС устройства/симулятора/эмулятора (например, 17.0 для iOS, 14 для Android).

automationName​

  • Тип: string
  • Обязательно: Нет
  • Значения: XCUITest (iOS), UiAutomator2 | Espresso (Android)

Драйвер автоматизации для использования. По умолчанию XCUITest для iOS и UiAutomator2 для Android.

Опции устройства​

deviceName​

  • Тип: string
  • Обязательно: Да

Имя устройства, симулятора или эмулятора для использования.

Примеры:

  • iOS Simulator: iPhone 15 Pro, iPad Air (5th generation)
  • Android Emulator: Pixel 7, Nexus 5X
  • Реальное устройство: Имя устройства, как показано в вашей системе

udid​

  • Тип: string
  • Обязательно: Нет (Требуется для реальных устройств iOS)

Уникальный идентификатор устройства. Требуется для реальных устройств iOS (40-символьный идентификатор) и рекомендуется для реальных устройств Android.

Как найти UDID:

  • iOS: Подключите устройство, откройте Finder/iTunes, нажмите на устройство → Серийный номер (нажмите, чтобы увидеть UDID)
  • Android: Выполните команду adb devices в терминале

Опции приложения​

appPath​

  • Тип: string
  • Обязательно: Нет*

Путь к файлу приложения для установки и запуска.

Поддерживаемые форматы:

  • iOS Simulator: директория .app
  • iOS Real Device: файл .ipa
  • Android: файл .apk

*Должен быть предоставлен либо appPath, либо noReset: true для подключения к уже запущенному приложению.

appWaitActivity​

  • Тип: string
  • Обязательно: Нет (Только для Android)

Активность, которую нужно дождаться при запуске приложения. Если не указано, используется основная активность приложения.

Пример: com.example.app.MainActivity

Опции состояния сессии​

noReset​

  • Тип: boolean
  • Обязательно: Нет
  • По умолчанию: false

Сохранять состояние приложения между сессиями. Когда true:

  • Данные приложения сохраняются (состояние входа, предпочтения и т.д.)
  • Сессия будет отсоединяться, а не закрываться (приложение продолжает работать)
  • Полезно для тестирования пользовательских путей в нескольких сессиях
  • Можно использовать без appPath для подключения к уже запущенному приложению

fullReset​

  • Тип: boolean
  • Обязательно: Нет
  • По умолчанию: true

Полностью сбросить приложение перед сессией. Когда true:

  • iOS: Удаляет и переустанавливает приложение
  • Android: Очищает данные и кэш приложения
  • Полезно для начала с чистого состояния

Установите fullReset: false с noReset: true для полного сохранения состояния приложения.

Таймаут сессии​

newCommandTimeout​

  • Тип: number
  • Обязательно: Нет
  • По умолчанию: 60

Сколько времени (в секундах) Appium будет ждать новой команды, прежде чем предположить, что клиент вышел, и завершить сессию. Увеличьте это значение для более длительных сессий отладки.

Примеры:

  • 60 - По умолчанию, подходит для большинства автоматизаций
  • 300 - 5 минут, для отладки или более медленных операций
  • 600 - 10 минут, для очень длительных тестов

Опции автоматической обработки​

autoGrantPermissions​

  • Тип: boolean
  • Обязательно: Нет
  • По умолчанию: true

Автоматически предоставлять разрешения приложению при установке/запуске. Когда true:

  • Разрешения на камеру, микрофон, местоположение и т.д. предоставляются автоматически
  • Не требуется ручная обработка диалогов разрешений
  • Оптимизирует автоматизацию, избегая всплывающих окон разрешений
Только для Android

Эта опция в основном влияет на Android. Разрешения iOS должны обрабатываться иначе из-за системных ограничений.

autoAcceptAlerts​

  • Тип: boolean
  • Обязательно: Нет
  • По умолчанию: true

Автоматически принимать системные предупреждения (диалоги), которые появляются во время автоматизации.

Примеры автоматически принимаемых предупреждений:

  • "Разрешить уведомления?"
  • "Приложение хочет получить доступ к вашему местоположению"
  • "Разрешить приложению доступ к фотографиям?"

autoDismissAlerts​

  • Тип: boolean
  • Обязательно: Нет
  • По умолчанию: false

Отклонять (отменять) системные предупреждения вместо их принятия. Имеет приоритет над autoAcceptAlerts при установке в true.

Переопределение сервера Appium​

Вы можете переопределить соединение с сервером Appium для каждой сессии:

appiumHost​

  • Тип: string
  • Обязательно: Нет

Хост сервера Appium. Переопределяет переменную окружения APPIUM_URL.

appiumPort​

  • Тип: number
  • Обязательно: Нет

Порт сервера Appium. Переопределяет переменную окружения APPIUM_URL_PORT.

appiumPath​

  • Тип: string
  • Обязательно: Нет

Путь сервера Appium. Переопределяет переменную окружения APPIUM_PATH.

Опции обнаружения элементов​

Опции для инструмента get_visible_elements.

elementType​

  • Тип: string
  • Обязательно: Нет
  • По умолчанию: interactable
  • Значения: interactable | visual | all

Тип возвращаемых элементов:

  • interactable: Кнопки, ссылки, поля ввода и другие кликабельные элементы
  • visual: Изображения, SVG и визуальные элементы
  • all: И интерактивные, и визуальные элементы

inViewportOnly​

  • Тип: boolean
  • Обязательно: Нет
  • По умолчанию: true

Возвращать только элементы, которые видны в текущей области просмотра. При false возвращает все элементы в иерархии представления (полезно для поиска элементов за пределами экрана).

includeContainers​

  • Тип: boolean
  • Обязательно: Нет
  • По умолчанию: false

Включать элементы-контейнеры/макеты в результаты. При true:

Включаемые контейнеры Android:

  • ViewGroup, FrameLayout, LinearLayout
  • RelativeLayout, ConstraintLayout
  • ScrollView, RecyclerView

Включаемые контейнеры iOS:

  • View, StackView, CollectionView
  • ScrollView, TableView

Полезно для отладки проблем с макетом или понимания иерархии представления.

includeBounds​

  • Тип: boolean
  • Обязательно: Нет
  • По умолчанию: false

Включать границы/координаты элементов (x, y, ширина, высота) в ответе. Установите true для:

  • Взаимодействия на основе координат
  • Отладки макета
  • Позиционирования визуальных элементов

Опции пагинации​

Для больших страниц с множеством элементов используйте пагинацию для уменьшения использования токенов:

limit​

  • Тип: number
  • Обязательно: Нет
  • По умолчанию: 0 (без ограничений)

Максимальное количество возвращаемых элементов.

offset​

  • Тип: number
  • Обязательно: Нет
  • По умолчанию: 0

Количество элементов, которые нужно пропустить перед возвратом результатов.

Пример: Получить элементы 21-40:

Get visible elements with limit 20 and offset 20

Опции дерева доступности​

Опции для инструмента get_accessibility (только для браузера).

limit​

  • Тип: number
  • Обязательно: Нет
  • По умолчанию: 100

Максимальное количество возвращаемых узлов. Используйте 0 для неограниченного количества (не рекомендуется для больших страниц).

offset​

  • Тип: number
  • Обязательно: Нет
  • По умолчанию: 0

Количество узлов, которые нужно пропустить для пагинации.

roles​

  • Тип: string[]
  • Обязательно: Нет
  • По умолчанию: Все роли

Фильтрация по определенным ролям доступности.

Общие роли: button, link, textbox, checkbox, radio, heading, img, listitem

Пример: Получить только кнопки и ссылки:

Get accessibility tree filtered to button and link roles

namedOnly​

  • Тип: boolean
  • Обязательно: Нет
  • По умолчанию: true

Возвращать только узлы, которые имеют имя/метку. Фильтрует анонимные контейнеры и уменьшает шум в результатах.

Опции снимков экрана​

Опции для инструмента take_screenshot.

outputPath​

  • Тип: string
  • Обязательно: Нет

Путь для сохранения файла скриншота. Если не указано, возвращает данные изображения в формате base64.

Автоматическая оптимизация​

Скриншоты автоматически обрабатываются для оптимизации потребления LLM:

ОптимизацияЗначениеОписание
Максимальный размер2000pxИзображения больше 2000px масштабируются
Максимальный размер файла1MBИзображения сжимаются до размера менее 1MB
ФорматPNG/JPEGPNG с максимальным сжатием; JPEG при необходимости для размера

Эта оптимизация гарантирует, что скриншоты могут быть эффективно обработаны без превышения лимитов токенов.

Поведение сессии​

Типы сессий​

Сервер MCP отслеживает типы сессий для предоставления соответствующих инструментов и поведения:

ТипОписаниеАвтоматическое отсоединение
browserСессия браузера ChromeНет
iosСессия приложения iOSДа (если noReset: true или нет appPath)
androidСессия приложения AndroidДа (если noReset: true или нет appPath)

Модель одной сессии​

Сервер MCP работает с моделью одной сессии:

  • Одновременно может быть активна только одна сессия браузера ИЛИ приложения
  • Запуск новой сессии закроет/отсоединит текущую сессию
  • Состояние сессии поддерживается глобально для всех вызовов инструментов

Отсоединение и закрытие​

Действиеdetach: false (Закрытие)detach: true (Отсоединение)
БраузерПолностью закрывает ChromeОставляет Chrome запущенным, отключает WebDriver
Мобильное приложениеЗавершает приложениеОставляет приложение запущенным в текущем состоянии
ПрименениеЧистое состояние для следующей сессииСохранение состояния, ручная проверка

Соображения по производительности​

Сервер MCP оптимизирован для эффективного общения с LLM с использованием формата TOON (Token-Oriented Object Notation), который минимизирует использование токенов при отправке данных в Claude.

Автоматизация браузера​

  • Режим без интерфейса быстрее, но не отображает визуальные элементы
  • Меньшие размеры окна сокращают время захвата скриншота
  • Обнаружение элементов оптимизировано с помощью единого выполнения скрипта
  • Оптимизация скриншотов сохраняет изображения менее 1МБ для эффективной обработки
  • inViewportOnly: true (по умолчанию) фильтрует только видимые элементы

Мобильная автоматизация​

  • Парсинг исходного кода XML страницы использует только 2 HTTP-вызова (против 600+ для традиционных запросов элементов)
  • Селекторы идентификаторов доступности самые быстрые и надежные
  • Селекторы XPath самые медленные - используйте только в крайнем случае
  • inViewportOnly: true (по умолчанию) значительно уменьшает количество элементов
  • Пагинация (limit и offset) уменьшает использование токенов для экранов с множеством элементов
  • includeBounds: false (по умолчанию) опускает данные о координатах, если они не нужны

Советы по использованию токенов​

НастройкаВлияние
inViewportOnly: trueФильтрует элементы вне экрана, уменьшая размер ответа
includeContainers: falseИсключает элементы макета (ViewGroup и т.д.)
includeBounds: falseОпускает данные x/y/ширина/высота
limit с пагинациейОбрабатывайте элементы партиями вместо всех сразу
namedOnly: true (доступность)Фильтрует анонимные узлы

Настройка сервера Appium​

Перед использованием мобильной автоматизации убедитесь, что Appium правильно настроен.

Базовая настройка​

# Установка Appium глобально
npm install -g appium

# Установка драйверов
appium driver install xcuitest    # iOS
appium driver install uiautomator2  # Android

# Запуск сервера
appium

Пользовательская конфигурация сервера​

# Запуск с пользовательским хостом и портом
appium --address 0.0.0.0 --port 4724

# Запуск с логированием
appium --log-level debug

# Запуск с определенным базовым путем
appium --base-path /wd/hub

Проверка установки​

# Проверка установленных драйверов
appium driver list --installed

# Проверка версии Appium
appium --version

# Проверка соединения
curl http://localhost:4723/status

Устранение проблем с конфигурацией​

Сервер MCP не запускается​

  1. Убедитесь, что npm/npx установлены: npm --version
  2. Попробуйте запустить вручную: npx @wdio/mcp
  3. Проверьте логи Claude Desktop на наличие ошибок

Проблемы с подключением к Appium​

  1. Убедитесь, что Appium запущен: curl http://localhost:4723/status
  2. Проверьте, что переменные окружения соответствуют настройкам сервера Appium
  3. Убедитесь, что брандмауэр разрешает соединения на порту Appium

Сессия не запускается​

  1. Браузер: Убедитесь, что Chrome установлен
  2. iOS: Проверьте, что Xcode и симуляторы доступны
  3. Android: Проверьте ANDROID_HOME и убедитесь, что эмулятор запущен
  4. Просмотрите логи сервера Appium для получения подробных сообщений об ошибках

Тайм-ауты сессии​

Если сессии истекают во время отладки:

  1. Увеличьте newCommandTimeout при запуске сессии
  2. Используйте noReset: true для сохранения состояния между сессиями
  3. Используйте detach: true при закрытии, чтобы приложение продолжало работать

Welcome! How can I help?

WebdriverIO AI Copilot