Playwright MCP

Введение

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

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

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

• Node.js 20 or newer
• An MCP client: VS Code, Cursor, Windsurf, Claude Code, Claude Desktop, or similar

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

Установка

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

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

VS Code

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

Или выполните установку через интерфейс командной строки 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.

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

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

Navigate to https://demo.playwright.dev/todomvc and add a few todo items.

Ассистент воспользуется инструментами 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-клиентов:

Run this Playwright code to verify the todo count:
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, чтобы отключить проверку активности.

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

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