Playwright MCP

Введение

Сервер Playwright MCP предоставляет возможности автоматизации браузера через Model Context Protocol, позволяя большим языковым моделям (LLM) взаимодействовать с веб-страницами с помощью структурированных снимков дерева доступности. Он работает с VS Code, Cursor, Windsurf, Claude Desktop и любым другим MCP-клиентом — модели с поддержкой обработки изображений не требуются.

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

Прежде чем начать, убедитесь, что у вас установлены:

• Node.js версии 20 или новее
• MCP-клиент: VS Code, Cursor, Windsurf, Claude Code, Claude Desktop или аналогичный

Начало работы

Установка

Добавьте сервер Playwright MCP в свой клиент, используя стандартную конфигурацию:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest"
      ]
    }
  }
}

VS Code

Нажмите одну из кнопок ниже для прямой установки:

Или установите через CLI VS Code:

code --add-mcp '{"name":"playwright","command":"npx","args":["@playwright/mcp@latest"]}'

Cursor

Или перейдите в Cursor Settings → MCP → Add new MCP Server, выберите тип подключения через команду и укажите npx @playwright/mcp@latest.

Claude Code

claude mcp add playwright npx @playwright/mcp@latest

Claude Desktop

Следуйте руководству по установке MCP и используйте стандартную конфигурацию, приведённую выше.

Другие клиенты

Стандартная конфигурация работает с большинством MCP-клиентов, включая Windsurf, Cline, Goose, Kiro, Codex, Copilot CLI и другие. О том, где разместить конфигурацию, читайте в документации по MCP вашего клиента.

Первое взаимодействие

После подключения сервера попросите своего ИИ-ассистента выполнить действия на веб-странице:

Перейди на https://demo.playwright.dev/todomvc и добавь несколько задач в список.

Ассистент воспользуется инструментами Playwright MCP, чтобы открыть браузер, перейти на страницу и взаимодействовать с элементами — всё это с помощью структурированных снимков дерева доступности, а не скриншотов.

Основные возможности

Снимки дерева доступности

Playwright MCP работает с деревом доступности страницы, а не с пикселями. При выполнении инструмент возвращает структурированный снимок, в котором показаны элементы страницы, их роли и текстовое содержимое. LLM использует ссылки на элементы из этих снимков для взаимодействия со страницей:

- heading "todos" [level=1]
- textbox "What needs to be done?" [ref=e5]
- listitem:
  - checkbox "Toggle Todo" [ref=e10]
  - text: "Buy groceries"

LLM читает этот снимок и использует ref=e5 для ввода текста в текстовое поле или ref=e10 для установки флажка.

Взаимодействие со страницами

Playwright MCP предоставляет инструменты для всех распространённых действий в браузере:

• Навигация: открытие URL-адресов, переход назад и вперёд, перезагрузка страниц.
• Нажатия и ввод текста: нажатие на элементы, ввод текста, заполнение форм, выбор значений в раскрывающихся списках.
• Скриншоты: создание снимков текущей страницы или отдельных элементов для визуальной проверки.
• Клавиатура и мышь: нажатие клавиш, наведение указателя, перетаскивание элементов.
• Диалоговые окна: подтверждение или отклонение диалоговых окон браузера.
• Вкладки: создание, закрытие вкладок браузера и переключение между ними.

Выполнение кода Playwright

Для сложных взаимодействий, выходящих за рамки отдельных вызовов инструментов, используйте инструмент browser_run_code_unsafe, чтобы выполнять скрипты Playwright напрямую. Этот инструмент выполняет произвольный JavaScript в процессе сервера Playwright и по своим возможностям эквивалентен удалённому выполнению кода (RCE) — включайте его только для доверенных MCP-клиентов:

Выполни этот код Playwright, чтобы проверить количество задач:
async (page) => {
  const count = await page.getByTestId('todo-count').textContent();
  return count;
}

Мониторинг сети и имитация ответов

Анализируйте сетевой трафик и имитируйте ответы API:

• Просмотр сетевых запросов: получение списка всех запросов, выполненных с момента загрузки страницы.
• Имитация маршрутов: настройка сопоставления URL-адресов с шаблонами для возврата заданных ответов.
• Сообщения консоли: доступ к выводу консоли браузера для отладки.

Состояние хранилища

Сохраняйте и восстанавливайте состояние браузера, включая файлы cookie и localStorage:

• Сохранение состояния: сохранение данных аутентификации и сеанса в файл.
• Восстановление состояния: загрузка ранее сохранённого состояния в новый сеанс.
• Управление файлами cookie: просмотр списка, получение, установка и удаление отдельных файлов cookie.

Инструменты WebMCP

Страницы могут регистрировать собственные инструменты для агентов через экспериментальный API WebMCP. Инструменты текущей вкладки предоставляются как MCP-инструменты с именами webmcp_<tool>.

Имена инструментов, их описания, схемы и результаты предоставляются страницей, поэтому рассматривайте их как недоверенные входные данные.

Настройка

Режим с графическим интерфейсом

По умолчанию Playwright MCP запускает браузер в режиме с графическим интерфейсом, чтобы вы могли видеть происходящее. Для запуска без графического интерфейса:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--headless"
      ]
    }
  }
}

Выбор браузера

Выберите, какой браузер использовать:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--browser=firefox"
      ]
    }
  }
}

Поддерживаемые значения: chrome, firefox, webkit, msedge.

Профиль пользователя

Playwright MCP поддерживает три режима работы с профилем:

• Постоянный (по умолчанию): состояние входа в систему и файлы cookie сохраняются между сеансами. Профиль хранится в ms-playwright/mcp-{channel}-{workspace-hash} в каталоге кеша вашей платформы, поэтому разные проекты автоматически получают отдельные профили. Путь можно переопределить с помощью --user-data-dir.
• Изолированный: каждый сеанс начинается с чистого состояния. Для включения передайте --isolated. Начальное состояние можно загрузить с помощью --storage-state.
• Расширение браузера: подключение к существующим вкладкам браузера с помощью расширения Playwright. Для включения передайте --extension.

Тайм-аут бездействия

Страница с непрерывной анимацией или отрисовкой потребляет ресурсы процессора всё время, пока открыт браузер, а сеанс агента может длиться часами. Поэтому браузер без графического интерфейса, запущенный сервером, закрывается через час без вызовов инструментов. Браузеры с графическим интерфейсом, а также браузеры, подключённые через --cdp-endpoint или --extension, автоматически не закрываются. Передайте --idle-timeout, чтобы задать тайм-аут в миллисекундах для любого режима, или 0, чтобы отключить его:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--idle-timeout=300000"
      ]
    }
  }
}

Если за этот промежуток времени не завершился ни один вызов инструмента, браузер закрывается независимо от наличия графического интерфейса — так же, как если бы вы закрыли его вручную. Следующий вызов инструмента запускает новый браузер, поэтому агент снова выполняет переход на страницу. Таймер никогда не срабатывает во время выполнения вызова инструмента.

• При использовании --isolated файлы cookie и данные хранилищ, находящиеся в памяти, теряются при закрытии из-за бездействия. Чтобы сохранить их, используйте постоянный профиль или --storage-state. У каждого клиента свой таймер: контекст бездействующего клиента закрывается, пока другие клиенты продолжают работать, а браузер закрывается, когда ни у одного клиента не остаётся контекста.
• При использовании --cdp-endpoint или --extension браузер не принадлежит серверу, поэтому тайм-аут по умолчанию отсутствует, а явно заданный тайм-аут лишь отключает сервер от браузера, оставляя его страницы открытыми. При использовании --extension следующий вызов инструмента снова проходит процедуру подключения.
• При использовании --shared-browser-context таймер охватывает всех клиентов: клиент, который бездействует, пока остальные продолжают работать, сохраняет свои вкладки и состояние, а общий браузер закрывается только после того, как каждый клиент бездействовал в течение заданного тайм-аута.

Файл конфигурации

Для расширенной настройки используйте файл конфигурации в формате JSON:

npx @playwright/mcp@latest --config path/to/config.json

Файл конфигурации поддерживает параметры браузера, параметры контекста, сетевые правила, тайм-ауты и многое другое. Полную схему см. в репозитории Playwright MCP.

Автономный сервер

При запуске браузера с графическим интерфейсом в системе без дисплея или из рабочих процессов IDE запустите MCP-сервер отдельно, используя HTTP-транспорт:

npx @playwright/mcp@latest --port 8931

В HTTP-сеансах используется тайм-аут проверки активности в пять секунд. Если ваш MCP-клиент или прокси не отвечает на ping-запросы, инициированные сервером, задайте для PLAYWRIGHT_MCP_PING_TIMEOUT_MS более длительный тайм-аут в миллисекундах. Установите значение 0, чтобы отключить проверку активности.

Затем укажите HTTP-адрес сервера в своём MCP-клиенте:

{
  "mcpServers": {
    "playwright": {
      "url": "http://localhost:8931/mcp"
    }
  }
}

Краткий справочник

Действие	Как выполнить
Установить сервер	Добавьте стандартную конфигурацию в свой MCP-клиент
Перейти на страницу	Попросите: «Перейди на https://example.com»
Нажать на элемент	Попросите: «Нажми кнопку Submit»
Заполнить форму	Попросите: «Введи test@example.com в поле электронной почты»
Сделать скриншот	Попросите: «Сделай скриншот страницы»
Выполнить код Playwright	Попросите: «Выполни этот код Playwright: ...»
Имитировать API	Попросите: «Настрой имитацию ответа эндпоинта /api/users, чтобы он возвращал ...»
Использовать режим с графическим интерфейсом	Включён по умолчанию. Передайте --headless, чтобы отключить
Выбрать браузер	Передайте --browser=firefox в args

Что дальше

• Пишите тесты с помощью проверок, адаптированных для веба, фикстур страниц и локаторов
• Запускайте тесты в CI
• Узнайте больше о Trace Viewer