> Инструкция написана для macOS. ## Суть проблемы Claude Code имеет встроенные инструменты для работы с вебом — `WebFetch` и `WebSearch`. Но у них есть существенное ограничение: они работают **без браузера**. Это означает: - **Нет JavaScript** — многие современные сайты (SPA, React/Vue/Angular-приложения) отдают пустую страницу без выполнения JS. Агент получает пустой HTML-шаблон вместо контента. - **Блокировка ботов** — сайты видят, что подключается не настоящий браузер, и блокируют доступ: капчи, Cloudflare-проверки, редиректы на страницу "Вы бот". - **Нет взаимодействия** — невозможно кликнуть по кнопке, заполнить форму, авторизоваться. В результате значительная часть интернета остаётся для AI-агента недоступной. Решение — подключить **настоящий браузер** через MCP-плагин, который будет открывать сайты как обычный пользователь, с полноценным рендерингом и выполнением JavaScript. ## Встроенные инструменты (без браузера) Несмотря на ограничения, встроенные инструменты по-прежнему полезны для простых задач: | Инструмент | Назначение | Ограничения | |---|---|---| | `WebSearch` | Поиск в интернете по ключевым словам | Работает хорошо, не требует браузера | | `WebFetch` | Загрузка и чтение содержимого страницы по URL | Не выполняет JS, блокируется защитой от ботов | `WebSearch` работает стабильно — это API-поиск, а не заход на сайт. `WebFetch` подходит для простых статических страниц (документация, API-справки, статьи без JS-рендеринга). Для всего остального нужен браузер. ## Решение 1: Playwright MCP — стандартный плагин Первый вариант решения — подключить настоящий браузер через **Playwright MCP**, официальный MCP-сервер от Microsoft. - Репозиторий: https://github.com/microsoft/playwright-mcp - Пакет: `@playwright/mcp` ### Конфигурация ```json { "mcpServers": { "playwright": { "type": "stdio", "command": "npx", "args": ["@playwright/mcp@latest"] } } } ``` ### Ограничение Playwright MCP решает основную проблему — сайты открываются в настоящем браузере с JavaScript, обходя блокировки ботов. Однако у него есть своё ограничение: он управляет **одним экземпляром браузера**. Если несколько субагентов одновременно пытаются его использовать, они конкурируют за одни и те же вкладки и мешают друг другу. Для параллельной работы этот плагин не подходит. ## Решение 2: Concurrent Browser MCP — параллельная работа **Concurrent Browser MCP** — MCP-сервер, построенный на Playwright, с поддержкой пула параллельных экземпляров браузера. Решает обе проблемы: сайты открываются в настоящем браузере (обход блокировок), и каждый субагент получает свой изолированный экземпляр (параллельная работа). - Репозиторий: https://github.com/sailaoda/concurrent-browser-mcp - Пакет: `concurrent-browser-mcp` ### Установка #### Шаг 0 — Убедиться, что установлен Node.js Concurrent Browser MCP работает на Node.js. Проверьте, установлен ли он: ```bash node -v ``` Если команда выдаёт версию (например, `v22.1.0`) — всё в порядке, переходите к шагу 1. Если команда не найдена — нужно установить Node.js. Самый простой способ на macOS — через Homebrew. Если Homebrew не установлен: ```bash /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" ``` Затем установить Node.js: ```bash brew install node ``` #### Шаг 1 — Установить пакет глобально ```bash npm install -g concurrent-browser-mcp ``` #### Шаг 2 — Установить браузеры Playwright Concurrent Browser MCP **не устанавливает браузеры автоматически**. Нужно скачать их отдельно: ```bash npx playwright install ``` Это скачает Chromium, Firefox и WebKit. Если нужен только Chromium: ```bash npx playwright install chromium ``` > Playwright использует **собственные** копии браузеров, а не системные. Они хранятся в `~/Library/Caches/ms-playwright/` (macOS). Установленный через Homebrew или App Store Chrome **не подойдёт**. #### Шаг 3 — Добавить в конфиг Claude Code Глобально (для всех проектов) — в `~/.claude.json`: ```json { "mcpServers": { "concurrent-browser": { "type": "stdio", "command": "npx", "args": [ "-y", "concurrent-browser-mcp", "--max-instances", "99" ] } } } ``` Или через CLI: ```bash claude mcp add concurrent-browser -s user -- npx -y concurrent-browser-mcp --max-instances 99 ``` #### Шаг 4 — Перезапустить Claude Code MCP-серверы подключаются при старте сессии. После изменения конфига нужно выйти и заново запустить `claude`. ### Параметры запуска При установке можно указать дополнительные параметры. Например, установка с нестандартным viewport и таймаутом: ```bash claude mcp add concurrent-browser -s user -- npx -y concurrent-browser-mcp --max-instances 99 --width 1920 --height 1080 --instance-timeout 60 ``` Если вы уже добавили этот MCP ранее и хотите изменить параметры — сначала удалите его, а потом добавьте заново с нужными параметрами: ```bash claude mcp remove concurrent-browser -s user claude mcp add concurrent-browser -s user -- npx -y concurrent-browser-mcp --max-instances 99 --width 1920 --height 1080 ``` После любых изменений перезапустить Claude Code. #### Доступные параметры | Параметр | Назначение | По умолчанию | |---|---|---| | `--max-instances N` | Максимум параллельных экземпляров браузера | 20 | | `--instance-timeout N` | Минут до автоматического закрытия неиспользуемого экземпляра | 30 | | `--browser TYPE` | Движок: `chromium`, `firefox`, `webkit` | chromium | | `--headless` | Запускать без окна (в фоне). См. баг ниже | true | | `--width N` | Ширина viewport в пикселях | 1280 | | `--height N` | Высота viewport в пикселях | 720 | | `--proxy URL` | Прокси-сервер | автоопределение | #### Примеры Минимальная конфигурация (99 параллельных экземпляров): ```bash claude mcp add concurrent-browser -s user -- npx -y concurrent-browser-mcp --max-instances 99 ``` С Firefox вместо Chromium: ```bash claude mcp add concurrent-browser -s user -- npx -y concurrent-browser-mcp --max-instances 99 --browser firefox ``` С увеличенным viewport и таймаутом 1 час: ```bash claude mcp add concurrent-browser -s user -- npx -y concurrent-browser-mcp --max-instances 99 --width 1920 --height 1080 --instance-timeout 60 ``` ### Баг: флаг --headless не принимает значение В текущей версии пакета (1.6.0) флаг `--headless` определён как чистый boolean без значения. Из-за этого: - `--headless false` — **не работает** (`false` игнорируется) - `--headless=false` — **не работает** - `--no-headless` — **не поддерживается** **Рабочий способ открывать видимое окно браузера** — передавать `headless: false` как параметр при вызове инструмента `browser_create_instance`. Это можно указать в инструкциях для агента (CLAUDE.md): ``` При создании экземпляра браузера (browser_create_instance) всегда передавай параметр headless: false. ``` ### Headless vs Headed режим | | Headless (по умолчанию) | Headed (с окном) | |---|---|---| | Окно браузера | Нет | Да, видно на рабочем столе | | Потребление ресурсов | Меньше RAM и CPU | Чуть больше | | Скорость | Чуть быстрее | Чуть медленнее | | Рендеринг | Полноценный, идентичный | Полноценный, идентичный | Сайт открывается одинаково в обоих режимах — тот же движок, тот же рендеринг, тот же JavaScript. Разница только в том, рисуются ли пиксели на экран. ## Альтернативные MCP-плагины для браузера Помимо Concurrent Browser MCP существуют и другие решения: | Плагин | Подход | Изоляция | Локальный | |---|---|---|---| | [Browserbase + Stagehand](https://github.com/browserbase/mcp-server-browserbase) | Облачные сессии | Полная | Нет (платный облачный сервис) | | [Ultimate Playwright MCP](https://lobehub.com/mcp/pm990320-ultimate-playwright-mcp) | Один Chrome, разные вкладки | По вкладкам | Да (нужен Chrome с CDP) | | [Playwright MCP Orchestrator](https://glama.ai/mcp/servers/mediar-ai/playwright-mcp-orchestrator) | Один Chrome, оркестрация сессий | По вкладкам | Да (нужен Chrome с CDP) | Плагины с пометкой "нужен Chrome с CDP" не запускают браузер сами — они подключаются к уже открытому Chrome. Перед использованием таких плагинов нужно вручную запустить Chrome в специальном режиме: 1. Закрыть Chrome, если он открыт 2. Открыть Терминал (Applications → Utilities → Terminal) 3. Вставить и выполнить команду: ```bash /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 ``` 4. Chrome откроется — не закрывать его, пока работаете с плагином После этого плагин сможет подключиться к этому Chrome через `http://localhost:9222`. Плюс такого подхода — AI-агент будет работать в вашем Chrome с вашими логинами, cookies и расширениями. Минус — каждый раз перед работой нужно запускать Chrome этой командой. ## Нюанс с Google при поиске через браузер Если AI-агент использует браузер для поиска в Google, Google может заблокировать запрос (капча, проверка на бота). Альтернативные поисковики, которые не блокируют автоматизированный доступ: | Поисковик | Блокирует ботов | |---|---| | DuckDuckGo | Нет | | Bing | Редко | | Brave Search | Нет | | Startpage | Редко | Но лучшее решение — использовать встроенный `WebSearch` для поиска, а браузер только для посещения сайтов и взаимодействия с интерфейсом. ## Когда какой инструмент использовать | Задача | Инструмент | |---|---| | Поиск информации в интернете | `WebSearch` | | Прочитать содержимое страницы | `WebFetch` | | Кликать по кнопкам, заполнять формы | Concurrent Browser MCP | | Авторизоваться на сайте | Concurrent Browser MCP | | Сделать скриншот страницы | Concurrent Browser MCP | | Взаимодействовать с веб-приложением | Concurrent Browser MCP | ## Готовая инструкция для AI-агента Скопируйте текст ниже и используйте одним из двух способов: - **В CLAUDE.md** — вставьте в файл `~/.claude/CLAUDE.md` (глобальные инструкции для всех проектов). Тогда Claude Code будет следовать этим правилам автоматически в каждой сессии. - **В промпт** — вставьте прямо в сообщение Claude Code перед вашим запросом. Подходит, если не хотите менять конфиг или нужно дать инструкцию разово. **Основная инструкция:** ``` # Браузер и веб-ресурсы ## Поиск в интернете Для поиска информации используй встроенный инструмент WebSearch. Никогда не используй браузер для поиска в интернете. ## Открытие веб-страниц Сначала попробуй WebFetch — он быстрее. Если сайт отдаёт пустую страницу, блокирует доступ или требует JavaScript — используй Concurrent Browser MCP. ``` **Дополнительно (если хотите, чтобы браузер открывался видимым окном):** ``` При создании экземпляра браузера (browser_create_instance) всегда передавай параметр headless: false, чтобы окно браузера открывалось визуально. ``` ## Ссылки - [Concurrent Browser MCP — GitHub](https://github.com/sailaoda/concurrent-browser-mcp) - [Playwright MCP — GitHub](https://github.com/microsoft/playwright-mcp) - [Browserbase MCP — GitHub](https://github.com/browserbase/mcp-server-browserbase) - [Claude Code MCP документация](https://code.claude.com/docs/en/mcp) - [Issue: параллельные агенты конфликтуют в Playwright MCP](https://github.com/microsoft/playwright-mcp/issues/893)