Перейти до основного вмісту

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

Ця сторінка документує всі параметри конфігурації для 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)

Activity, яку слід очікувати при запуску додатку. Якщо не вказано, використовується основна/стартова activity додатку.

Приклад: 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:

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

Ця оптимізація гарантує, що знімки екрану можуть бути ефективно оброблені без перевищення лімітів токенів.

Поведінка сесії​

Типи сесій​

MCP сервер відстежує типи сесій для надання відповідних інструментів і поведінки:

ТипОписАвто-відʼєднання
browserСесія браузера ChromeНі
iosСесія iOS додаткуТак (якщо noReset: true або немає appPath)
androidСесія Android додаткуТак (якщо noReset: true або немає appPath)

Модель одиночної сесії​

MCP сервер працює за моделлю одиночної сесії:

  • Одночасно може бути активною лише одна сесія браузера АБО додатку
  • Запуск нової сесії закриє/від'єднає поточну сесію
  • Стан сесії підтримується глобально для всіх викликів інструментів

Відʼєднання vs Закриття​

Діяdetach: false (Закрити)detach: true (Відʼєднати)
БраузерПовністю закриває ChromeЗалишає Chrome запущеним, від'єднує WebDriver
Мобільний додатокЗавершує додатокЗалишає додаток запущеним в поточному стані
Випадок використанняЧистий стан для наступної сесіїЗбереження стану, ручна інспекція

Міркування щодо продуктивності​

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

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

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

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

  • Аналіз XML вихідного коду сторінки використовує лише 2 HTTP виклики (проти 600+ для традиційних запитів елементів)
  • Селектори Accessibility ID найшвидші та найнадійніші
  • Селектори 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