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, чтобы отключить проверку соединения.

Затем укажите в своём 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` в аргументах

Введение​

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

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

Установка​

VS Code​

Cursor​

Claude Code​

Claude Desktop​

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Что дальше​