Claude MCP Playwright: полное руководство по интеграции

Model Context Protocol от Anthropic позволяет Claude Code напрямую управлять браузером через Playwright — без скриншотов и vision-моделей. Пакет @playwright/mcp превращает Claude в мощный инструмент автоматизации, работающий через дерево доступности (accessibility tree) для детерминированного взаимодействия с веб-страницами. Одна команда claude mcp add playwright npx @playwright/mcp@latest подключает более 20 инструментов для навигации, кликов, заполнения форм и E2E-тестирования.

Что такое MCP и как работает связка с Playwright

Model Context Protocol — открытый протокол Anthropic для подключения LLM к внешним инструментам и источникам данных. MCP-серверы предоставляют tools (инструменты), resources (ресурсы) и prompts (подсказки), которые Claude может использовать во время сессии. Ключевое отличие от классических API: Claude сам решает, когда и какой инструмент вызвать.

Playwright MCP-сервер от Microsoft работает по принципу stdio-транспорта — Claude Code запускает процесс npx @playwright/mcp@latest, который открывает браузер и выполняет команды. Вместо анализа пикселей сервер возвращает accessibility snapshot — структурированное представление DOM с элементами, их ролями и атрибутами. Это делает автоматизацию быстрой и надёжной: нет зависимости от рендеринга и позиций элементов.

Технические характеристики пакета:

Версия: 0.0.48 (актуальная на ноябрь 2025)
Требования: Node.js 18+
Браузеры: Chromium, Firefox, WebKit, Chrome, Edge
Лицензия: Apache-2.0
GitHub: microsoft/playwright-mcp (23.7k звёзд)

Установка и настройка: три шага к работающей интеграции

Шаг 1. Добавление MCP-сервера в Claude Code

Основная команда для подключения Playwright MCP к Claude Code CLI:

claude mcp add playwright npx @playwright/mcp@latest

Эта команда регистрирует сервер в локальной конфигурации. Для командной работы используйте scope-флаги:

# Для текущего пользователя (все проекты)
claude mcp add --scope user playwright npx @playwright/mcp@latest

# Для проекта (сохраняется в .mcp.json, можно закоммитить)
claude mcp add --scope project playwright npx @playwright/mcp@latest

На Windows (не WSL) требуется обёртка cmd:

claude mcp add playwright -- cmd /c npx -y @playwright/mcp@latest

Шаг 2. Установка браузеров

MCP-сервер требует установленные браузеры Playwright. Выполните до первого запуска:

# Все браузеры по умолчанию
npx playwright install

# С системными зависимостями (для Linux/CI)
npx playwright install --with-deps

# Конкретный браузер
npx playwright install chromium
npx playwright install firefox
npx playwright install webkit

Шаг 3. Проверка подключения

# Список добавленных серверов
claude mcp list

# Детали конкретного сервера
claude mcp get playwright

# Внутри сессии Claude Code
/mcp

Команда /mcp показывает статус подключения (connected/failed) и список доступных инструментов.

Конфигурация через JSON и CLI-флаги

JSON-конфигурация для Claude Desktop и IDE

Файл конфигурации располагается:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%Claudeclaude_desktop_config.json
Проект: .mcp.json в корне репозитория

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

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

Расширенная конфигурация с опциями:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--browser", "firefox",
        "--headless",
        "--viewport-size", "1280x720",
        "--caps", "testing,pdf"
      ]
    }
  }
}

Ключевые CLI-флаги сервера

Флаг | Описание | Значение

--browser | Браузер | chromium, firefox, webkit, msedge

--headless | Режим без GUI | —

--isolated | Не сохранять профиль | —

--user-data-dir | Путь к профилю | /path/to/profile

--viewport-size | Размер окна | 1280×720

--caps | Дополнительные возможности | vision, pdf, tabs, testing, tracing

--timeout-action | Таймаут действия | 5000 (мс)

--timeout-navigation | Таймаут навигации | 60000 (мс)

--storage-state | Файл с авторизацией | .auth/state.json

Инструменты Playwright MCP: полный список

После подключения Claude получает доступ к более чем 20 инструментам:

Базовая автоматизация:

browser_navigate — переход по URL
browser_click — клик по элементу (поддержка double-click, модификаторов)
browser_type — ввод текста
browser_fill_form — заполнение нескольких полей формы
browser_select_option — выбор в dropdown
browser_hover — наведение курсора
browser_drag — drag-and-drop
browser_press_key — нажатие клавиши

Анализ страницы:

browser_snapshot — accessibility-снимок страницы (основной инструмент)
browser_take_screenshot — скриншот
browser_console_messages — логи консоли
browser_network_requests — сетевые запросы

Управление:

browser_tabs — работа с вкладками (list, create, close, select)
browser_wait_for — ожидание элемента/текста
browser_handle_dialog — обработка alert/confirm/prompt
browser_file_upload — загрузка файлов
browser_resize — изменение размера окна
browser_install — установка браузера через MCP

Дополнительные возможности (активируются через --caps):

testing: browser_generate_locator, browser_verify_element_visible, browser_verify_text_visible
vision: browser_mouse_click_xy, browser_mouse_move_xy (координатный ввод)
pdf: browser_pdf_save
tracing: browser_start_tracing, browser_stop_tracing

Практические примеры промптов

Первый запуск и навигация

При первом обращении явно указывайте «playwright mcp» — иначе Claude может использовать bash:

Используй playwright mcp, чтобы открыть браузер и перейти на example.com

Парсинг и извлечение данных

Открой amazon.com, найди 'wireless headphones', извлеки названия и цены первых 5 товаров в CSV-файл

E2E-тестирование с BDD-стилем

Given: перейди на http://eaapp.somee.com и нажми Login
And: введи логин "admin" и пароль "password", выполни вход
Then: перейди на страницу Employee List
And: нажми "Create New", заполни форму реалистичными данными сотрудника

Комплексный тест покупки

Выполни тест покупки на https://www.saucedemo.com:
1. Войди с логином "standard_user" и паролем "secret_sauce"
2. Добавь "Sauce Labs Backpack" в корзину
3. Добавь "Sauce Labs Bike Light" в корзину
4. Перейди в корзину, проверь наличие обоих товаров
5. Оформи заказ: John Doe, zip 12345
6. Заверши покупку и проверь сообщение об успехе
7. Выйди из аккаунта

Генерация Playwright-тестов

Исследуй сайт localhost:3000, протестируй основную функциональность,
сгенерируй TypeScript-тест с @playwright/test, сохрани в tests/ и запусти.
Итерируй до прохождения теста.

Типичные проблемы и решения

Ошибка «Browser executable doesn’t exist»

Причина: Браузеры не установлены.

npx playwright install --with-deps

Ошибка «Browser is already in use»

Причина: Повторный запуск с тем же профилем.

Решение: Добавьте флаг --isolated:

{"args": ["@playwright/mcp@latest", "--isolated"]}

MCP-сервер запускается, но инструменты недоступны

Решения:

Используйте конкретную версию вместо @latest: @playwright/mcp@0.0.48
Установите браузеры вручную перед запуском
Полностью перезапустите IDE/Claude Desktop

Windows: ошибки JSON-синтаксиса

Решение для PowerShell:

$config = @{name="playwright"; command="npx"; args=@("@playwright/mcp@latest")}
code --add-mcp ($config | ConvertTo-Json -Compress)

Claude использует bash вместо MCP

Решение: В первом промпте явно укажите «playwright mcp»:

Use playwright mcp to navigate to example.com

Permission denied при установке браузеров

Установка системных зависимостей требует sudo:

sudo npx playwright install-deps  # Системные зависимости
npx playwright install            # Сами браузеры (без sudo)

E2E-тестирование через Claude Code

Активация инструментов тестирования

claude mcp add playwright -- npx @playwright/mcp@latest --caps testing

Это добавляет инструменты browser_verify_element_visible, browser_verify_text_visible, browser_generate_locator.

Структура промпта для генерации тестов

Три компонента хорошего промпта:

Окружение: URL, состояние авторизации, тестовые данные
Сценарий: Конкретные шаги и проверки
Инструкции: Как генерировать и сохранять тест

Работа с авторизацией

Для тестов с логином используйте --storage-state:

# Сначала залогиньтесь вручную в headed-режиме, сохраните состояние
# Затем используйте его в CI
npx @playwright/mcp@latest --isolated --storage-state .auth/user.json

Playwright Agents (v1.56+)

Новая система агентов автоматизирует создание тестов:

npx playwright init-agents --loop=vscode

Planner — исследует приложение, создаёт Markdown-планы
Generator — конвертирует планы в TypeScript-тесты
Healer — запускает тесты, автоматически исправляет падающие

Интеграция в CI/CD

name: Playwright Tests
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v5
    - uses: actions/setup-node@v6
      with:
        node-version: lts/*
    - run: npm ci
    - run: npx playwright install --with-deps
    - run: npx playwright test
    - uses: actions/upload-artifact@v5
      if: ${{ !cancelled() }}
      with:
        name: playwright-report
        path: playwright-report/

Заключение

Интеграция Claude Code с Playwright MCP превращает написание E2E-тестов в диалог на естественном языке. Ключевые преимущества: детерминированность через accessibility tree, более 20 готовых инструментов, поддержка всех основных браузеров и гибкая конфигурация через JSON или CLI. Для продуктивной работы достаточно трёх команд: claude mcp add, npx playwright install и описания задачи в промпте. При возникновении проблем проверяйте установку браузеров, используйте --isolated для изоляции профилей и явно указывайте «playwright mcp» в первом обращении.

Часто задаваемые вопросы: Claude MCP Playwright

Claude Code не видит инструмент ‘playwright’. Что делать?

Диагностика проблемы:

Выполните проверку статуса MCP-сервера внутри сессии Claude Code:
/mcp
Команда отобразит список подключенных серверов и их статус (connected/failed). Если playwright отсутствует или имеет статус failed, применяйте следующие методы устранения:
Решения по приоритету:
Проверка области видимости (scope)
Убедитесь, что сервер добавлен с корректным scope-флагом
Для пользовательского уровня: claude mcp add --scope user playwright npx @playwright/mcp@latest
Для проектного уровня: claude mcp add --scope project playwright npx @playwright/mcp@latest
Верификация конфигурации
claude mcp get playwright
Команда выведет детали конфигурации сервера. Проверьте корректность пути к исполняемому файлу npx.
Полная переустановка
claude mcp remove playwright claude mcp add --scope user playwright npx @playwright/mcp@latest
Проверка Node.js окружения
Минимальная версия: Node.js 18+
Проверка: node --version
Доступность npx: npx --version

При запуске появляется ошибка «browsers not installed»

Причина: MCP-сервер Playwright требует предустановленные браузеры, которые не устанавливаются автоматически.
Решение:
# Установка всех поддерживаемых браузеров npx playwright install # Установка с системными зависимостями (рекомендуется для Linux/CI) npx playwright install --with-deps # Установка конкретного браузера npx playwright install chromium
Важно: На Linux-системах установка системных зависимостей может требовать sudo-прав:
# Сначала системные зависимости (с sudo) sudo npx playwright install-deps # Затем браузеры (без sudo) npx playwright install
Верификация установки:
# Проверка установленных браузеров npx playwright --version

Ошибка «Browser is already in use» при повторном запуске

Причина: MCP-сервер пытается повторно использовать профиль браузера, который уже активен.
Рекомендуемое решение: Активируйте изолированный режим работы
Через CLI:
claude mcp add playwright -- npx @playwright/mcp@latest --isolated
Через JSON-конфигурацию:
{ "mcpServers": { "playwright": { "command": "npx", "args": ["@playwright/mcp@latest", "--isolated"] } } }
Флаг --isolated гарантирует создание временного профиля браузера для каждой сессии без сохранения состояния.

Windows: синтаксические ошибки при добавлении сервера

Проблема: Прямое выполнение npx на Windows (не WSL) может приводить к ошибкам запуска.
Решение: Используйте обёртку через cmd:
claude mcp add playwright -- cmd /c npx -y @playwright/mcp@latest
Альтернатива для PowerShell:
$config = @{ name = "playwright" command = "cmd" args = @("/c", "npx", "-y", "@playwright/mcp@latest") } code --add-mcp ($config | ConvertTo-Json -Compress)

Могу ли я использовать Playwright с Python или Java через MCP?

Краткий ответ: Официальный MCP-сервер работает на Node.js, но язык клиентского кода не имеет значения.
Детальное объяснение:
Model Context Protocol является языконезависимым протоколом взаимодействия. MCP-сервер @playwright/mcp написан на Node.js и управляет браузером через JavaScript-версию Playwright. Однако Claude Code не генерирует и не выполняет код на стороне клиента — он отправляет команды на сервер через протокол MCP.
Практические следствия:
• Claude Code может генерировать тесты на любом языке (Python, Java, C#, Go) • Выполнение автоматизации через MCP происходит независимо от языка генерируемого кода • Для Python-проектов Claude может создавать pytest-тесты, которые запускаются локально • Для Java-проектов — JUnit/TestNG тесты с аналогичным подходом
Альтернативный подход для Python:
Если требуется Python-специфичная интеграция, рассмотрите создание собственного MCP-сервера на базе Playwright для Python:
# Концептуальный пример структуры # Требует реализации MCP-протокола на Python from playwright.sync_api import sync_playwright from mcp import Server # гипотетическая библиотека server = Server("playwright-python") # Регистрация инструментов и обработчиков

Как передать конфиденциальные данные (логины, пароли) через Claude?

Критически важно: Никогда не включайте чувствительные данные непосредственно в промпты.
Рекомендуемые методы:
1. Переменные окружения (environment variables)
Создайте .env файл в директории проекта:
# .env TEST_USERNAME=admin TEST_PASSWORD=secure_password_123 STRIPE_API_KEY=sk_test_xxxxx
В промпте для Claude:
Используй переменные окружения для авторизации: - username из переменной TEST_USERNAME - password из переменной TEST_PASSWORD Выполни вход на сайт example.com
Claude сгенерирует код, который читает переменные окружения вместо жёсткого кодирования значений.
2. Файл состояния авторизации (storage state)
Для повторного использования авторизованной сессии:
# Первый запуск: ручной вход в headed-режиме npx @playwright/mcp@latest --storage-state .auth/user.json # Последующие запуски используют сохранённое состояние npx @playwright/mcp@latest --storage-state .auth/user.json --headless
3. Параметризация через конфигурационные файлы
Создайте config.json (добавьте в .gitignore):
{ "credentials": { "staging": { "username": "test_user", "password": "test_pass" } } }
Claude может читать файл и использовать данные без их явного указания в промпте.

Может ли Claude Code автоматически создавать сложные E2E-тесты?

Да. Это основной сценарий использования интеграции MCP + Playwright.
Возможности генерации:
Claude Code способен: • Исследовать веб-приложение через browser_snapshot • Идентифицировать интерактивные элементы и их локаторы • Генерировать полноценные test suites на TypeScript/JavaScript • Создавать тесты с проверками (assertions) и обработкой ошибок • Организовывать тесты в файловой структуре Playwright-проекта
Пример промпта для генерации теста:
Исследуй приложение на localhost:3000: 1. Проанализируй основные user flows 2. Создай E2E-тест для процесса регистрации пользователя 3. Включи проверки для каждого шага 4. Сохрани в tests/registration.spec.ts 5. Запусти тест и исправь ошибки при необходимости
Ожидаемый результат:
Claude создаст файл tests/registration.spec.ts с полноценным тестом, включающим: • Импорты необходимых зависимостей • Структуру test suite с beforeEach/afterEach • Локаторы элементов (по возможности с data-testid) • Assertions через expect() • Обработку асинхронных операций
Ограничения:
• Сложные SPA с динамической загрузкой могут требовать ручной корректировки wait-условий • Капчи и двухфакторная аутентификация требуют обходных решений • Visual regression testing нуждается в дополнительной настройке плагинов
Как получить доступ к файлам, созданным Playwright локально?
Механизм работы:
Playwright MCP-сервер выполняется в том же окружении, что и Claude Code, следовательно имеет доступ к локальной файловой системе.
Сценарии работы с файлами:
1. Скриншоты и PDF
Промпт:
Открой страницу example.com, сделай скриншот и сохрани в ./screenshots/homepage.png
Claude выполнит browser_take_screenshot с указанным путём. Файл сохраняется локально и доступен для дальнейшего анализа:
Проанализируй скриншот ./screenshots/homepage.png и опиши UI-проблемы
2. Загруженные файлы (downloads)
Перейди на example.com/report, нажми кнопку "Скачать Excel", дождись завершения загрузки, затем прочитай файл и извлеки данные
Claude автоматически обрабатывает директорию загрузок браузера и может работать с полученными файлами.
3. Трейсы (traces) для отладки
При активации capability tracing:
npx @playwright/mcp@latest --caps tracing
Можно записывать детальные логи выполнения:
Начни запись трейса, выполни тест корзины покупок, останови запись и сохрани в ./traces/cart-test.zip
Полученный файл открывается через Playwright Trace Viewer:
npx playwright show-trace ./traces/cart-test.zip