Playwright MCP — Claude Code: с нуля до уверенной работы

До сих пор агент правил фронтенд вслепую. Он менял разметку и стили, но не видел результата: отрисовалась ли страница, не разъехалась ли вёрстка, отправляется ли форма. Проверяли всегда вы — открывали браузер, смотрели, возвращались в терминал и пересказывали агенту, что не так. Этот пересказ и есть узкое место: агент делает шаг и останавливается, пока вы не опишете ему последствия.

Playwright MCP убирает посредника. Это локальный сервер, который даёт Claude Code настоящий браузер: агент открывает адрес, кликает, читает содержимое страницы. Цикл замыкается — правка, открытие страницы, проверка, следующая правка — и всё это без вашего участия на каждом шаге.

Что уже умеем / что добавим

В уроке 9.3 вы подключили базу данных и увидели, как выглядит рабочий MCP-сервер, дающий агенту доступ к внешним данным. Это был доступ на чтение фактов.

Playwright — второй практический сервер главы, и смысл у него принципиально другой. База отвечает на вопросы о данных; браузер даёт агенту возможность увидеть результат собственной работы. В этом уроке мы подключим его, сделаем первый прогон, впишем в .mcp.json рядом с уже настроенным сервером и разберём, чего это стоит в контексте и в безопасности.

Что вы узнаете в рамках статьи

Как подключить Playwright MCP одной командой и что означает каждая её часть
Как убедиться, что сервер действительно подключился, а не просто сохранился в конфигурации
Как выглядит рабочий цикл «правка — открытие страницы — проверка»
Как описать локальный сервер в .mcp.json и почему браузер связан с темой prompt injection
Сколько контекста стоит браузерный сервер и как диагностировать stdio-подключение

Ключевые термины

stdio-сервер — MCP-сервер, который Claude Code запускает у вас на машине как подпроцесс и общается с ним через стандартные потоки ввода-вывода. Транспорт по умолчанию.
Playwright MCP — сервер @playwright/mcp, предоставляющий агенту инструменты управления браузером: навигацию, клики, чтение содержимого страницы.
Разделитель -- — граница между опциями команды claude и командой запуска сервера. Всё, что после него, передаётся серверу без изменений.
MAX_MCP_OUTPUT_TOKENS — переменная окружения, задающая предел объёма вывода MCP-инструмента. По умолчанию 25 000 токенов.

Подключение

Команда короткая, но каждая её часть значима:

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

От примеров с размещённым сервером её отличают три вещи. Первое: нет флага --transport. Локальные серверы используют транспорт stdio по умолчанию, указывать его не нужно. Второе: всё после -- — это команда запуска сервера, а не опции Claude Code. Третье: -y велит npx установить пакет без вопросов, иначе первый запуск застрянет на подтверждении.

Требование одно — Node.js 18 или новее. Отдельно устанавливать браузер не нужно: Playwright управляет тем Chrome, который уже есть на машине. Если нужен другой браузер, добавьте флаг --browser с именем после @playwright/mcp@latest:

claude mcp add playwright -- npx -y @playwright/mcp@latest --browser firefox

Проверка и первый прогон

Сообщение «Added» после добавления означает ровно одно: запись сохранена в конфигурации. Оно не говорит, что команда запускается и сервер работает. Проверяем отдельно:

claude mcp list

Нужен статус Connected. Если первая проверка показывает статус Failed to connect — скорее всего, npx ещё скачивает пакет и подключение не уложилось в таймаут. Подождите и повторите.

Когда сервер подключён, попросите агента открыть страницу:

Use playwright to open <https://example.com> and tell me the page title

Что вы увидите: на экране открывается окно браузера, а в выводе Claude появляются вызовы инструментов, помеченные именем сервера playwright и действием — например, browser_navigate. Это те самые инструменты вида mcp__playwright__browser_navigate, о которых шла речь в уроке 9.1.

Рабочий цикл

Документация называет два применения: направить агента на локальный dev-сервер и проверить, что страница по-прежнему отображается после изменения, и пройти шаги из баг-репорта.

Разверните это в цикл. Агент правит компонент, открывает страницу на локальном адресе, читает результат, видит расхождение и правит дальше. Вы включаетесь не на каждой итерации, а тогда, когда цикл сошёлся или явно застрял. Качественно это другое взаимодействие: раньше глазами агента были вы.

Место в конфигурации проекта

Чтобы сервер получила вся команда, опишите его в .mcp.json рядом с уже настроенными:

{
  "mcpServers": {
    "claude-code-docs": {
      "type": "http",
      "url": "<https://code.claude.com/docs/mcp>"
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

Видно, как то, что в командной строке шло после --, раскладывается по command и args. Серверы области project требуют одобрения: Claude Code спросит подтверждение в интерактивной сессии, прежде чем их использовать.

И прямо, без нагнетания, про урок 9.2. Браузерный сервер видит те страницы, куда вы его пустили, и возвращает их содержимое в контекст модели. Это ровно тот канал prompt injection, о котором был отдельный урок: текст со страницы попадает в контекст как данные, но может быть написан как инструкция. Направляя агента на внешний сайт, помните об этом.

Цена в контексте и диагностика

Каждый подключённый сервер занимает место в контекстном окне: имена его инструментов и инструкции загружаются в каждую сессию. Удаление неиспользуемых серверов это место освобождает:

claude mcp remove playwright

Браузерный сервер к тому же отдаёт много текста. Claude Code предупреждает, когда вывод MCP-инструмента превышает 10 000 токенов; максимум по умолчанию — 25 000, и он поднимается переменной окружения:

export MAX_MCP_OUTPUT_TOKENS=50000

Ещё одна особенность, которая для браузера вполне реальна: вызов MCP-инструмента дольше двух минут переводится в фоновую задачу, чтобы не блокировать сессию.

Если сервер не подключился, диагностика для stdio простая — выполните настроенную команду прямо в терминале:

npx -y @playwright/mcp@latest

Если она запускается и ждёт ввода, сервер исправен и дело в конфигурации. Если падает, сообщение назовёт, чего не хватает — например, Node.js или браузера. Проверьте также, что записано в конфигурации:

claude mcp get playwright

Если показанная команда отличается от той, что вы набирали, скорее всего пропущен разделитель --. А если подключение не укладывается в стартовый таймаут, поднимите его через MCP_TIMEOUT.

Частые ошибки

Считать «Added» подтверждением работы. Эта строка сообщает лишь о сохранении записи. Реальное состояние показывает claude mcp list со статусом статус Connected.
Добавлять -transport http к локальному серверу. Playwright запускается как процесс на вашей машине, у него нет URL. Транспорт stdio используется по умолчанию, флаг не нужен вовсе.
Пропустить - перед npx. Без разделителя аргументы команды запуска разбираются как опции claude mcp add, и в конфигурации окажется не то, что вы набирали. Сверьтесь через claude mcp get.
Держать браузер подключённым постоянно. Сервер расходует контекст в каждой сессии и отдаёт объёмный вывод. Если браузер сейчас не нужен, уберите его через claude mcp remove.

Наиболее частые вопросы

Нужно ли отдельно устанавливать браузер? — Нет. Playwright управляет тем Chrome, который уже установлен на машине. Другой браузер задаётся флагом -browser после @playwright/mcp@latest.
Почему для браузера stdio, а не http? — Серверу нужен доступ к локальному ресурсу — браузеру на вашей машине. Размещённый сервис по URL до него не дотянется.
Первая проверка показала статус Failed to connect. Всё сломано? — Скорее всего нет: npx скачивает пакет при первом запуске. Подождите и повторите, при необходимости увеличьте MCP_TIMEOUT.
Вызов браузера идёт долго и сессия будто зависла. — Вызов MCP-инструмента дольше двух минут переводится в фоновую задачу, сессия при этом остаётся доступной.
Насколько опасно пускать агента на внешние сайты? — Содержимое страницы попадает в контекст модели, а значит, работает канал prompt injection из урока 9.2. Для проверки собственного dev-сервера риск минимален, для произвольных сайтов — нет.

Итоги

Вы подключили второй практический сервер и сделали агенту то, чего у него не было всю дорогу: глаза. Теперь он открывает страницу, читает результат своей правки и продолжает работу сам, а вы включаетесь на осмысленных точках, а не на каждой итерации. Попутно вы научились отличать сохранённую запись от работающего подключения, диагностировать stdio-сервер запуском его команды вручную и трезво оценивать, во что обходится подключённый сервер в контексте.

Дальше мы соберём всё вместе. В следующем уроке вас ждёт упражнение: вы напишете скилл, который проверяет данные через подключённый MCP-сервер. Там сойдутся скиллы из седьмой главы и MCP из этой — процедуру задаёте вы, а данные агент берёт из реальной системы.