chrome-debug-mcp

chrome-debug-mcp — это асинхронный Model Context Protocol (MCP) сервер на Rust, который позволяет AI-агентам и большим языковым моделям нативно управлять, автоматизировать и отлаживать браузеры на базе Chromium через Chrome DevTools Protocol (CDP).

Используя под капотом cdp-browser-lite (который, в свою очередь, реэкспортирует клиент cdp-lite), этот MCP-сервер напрямую подключается к браузеру, избегая тяжёлых абстракций, что позволяет проводить сеансы живой отладки прямо из вашего редактора или чат-интерфейса. Начиная с v0.2.0, он также может автоматически управлять жизненным циклом процесса Chrome.

✨ Возможности

Этот сервер нативно реализует набор инструментов, сгруппированных по доменам CDP и нативному управлению процессами:

🛡️ Конфиденциальность и безопасность

• Изолированные профили (по умолчанию): Каждый раз, когда MCP-сервер запускает Chrome, он создаёт новый временный пользовательский профиль во временном каталоге вашей системы. Этот профиль полностью независим от вашего основного профиля браузера и удаляется при остановке браузера — файлы cookie, история, сохранённые пароли или данные сеанса из одного сеанса никогда не переходят в следующий.

• Режим, похожий на инкогнито: По умолчанию управляемому экземпляру не передаются файлы cookie, история, сохранённые пароли или данные сеансов из ваших личных учётных записей.

• Защита личности: Даже если LLM имеет полный контроль над браузером, она не может получить доступ к вашим авторизованным сеансам (например, Google, GitHub, банковские сервисы) или выдать себя за вас без явного разрешения.

• Режим пользовательского профиля: Используйте флаг --user-profile, чтобы запустить Chrome с существующим системным профилем. Это полезно, когда вы хотите, чтобы LLM работала в рамках ваших активных сеансов (файлы cookie, сохранённые логины и т.д.) без повторной аутентификации на каждом сайте. Используйте с осторожностью, так как это даёт LLM доступ к вашим личным данным браузера.

  • ⚠️ Примечание о --user-profile: Из-за синглтонной архитектуры Chrome, если ваш браузер уже открыт, он делегирует запрос и не сможет открыть порт отладки. Вам нужно либо закрыть все существующие экземпляры Chrome перед запуском MCP, либо запустить браузер вручную с флагом --remote-debugging-port=9222.

🚀 Управление экземплярами Chrome и вкладками

• Поддержка нескольких экземпляров: Запускает и управляет несколькими параллельными независимыми процессами Chrome на динамических портах, каждый со своим изолированным каталогом профиля. Ограничьте количество экземпляров с помощью флага --max-instances.

• Инструменты реестра экземпляров: Используйте open_instance, list_instances и close_instance для создания, проверки и очистки дополнительных экземпляров. Все существующие инструменты принимают необязательный параметр instance_id для маршрутизации команд в целевой браузер.

• Поддержка нескольких вкладок (новое): Управляет несколькими параллельными вкладками в одном экземпляре Chrome, мультиплексируя потоки событий и команды через одно WebSocket-соединение.

  • Автообнаружение: Всплывающие окна, открытые целевыми страницами (например, window.open()), автоматически обнаруживаются, подключаются и регистрируются в реестре вкладок сеанса.

  • Изоляция кэша: Кэши состояния (сообщения консоли, сетевой трафик, скрипты, разобранные отладчиком, инструменты WebMCP) строго изолированы по вкладкам, поэтому события не пересекаются между целевыми объектами.

• Инструменты реестра вкладок (новое):

  • open_tab — Открывает новую вкладку, опционально с пользовательской меткой и целевым URL. Возвращает JSON с tab_id для использования в других инструментах.

  • list_tabs — Выводит список всех открытых и зарегистрированных вкладок экземпляра в виде JSON (tab_id, label, target_id, url), а также текущую активную вкладку. Если вкладки не зарегистрированы, инструменты используют стандартное подключение экземпляра с одной вкладкой.

  • close_tab — Закрывает конкретную вкладку по ID и очищает её кэш состояния. Возвращает новую активную вкладку.

  • switch_tab — Изменяет активную вкладку по умолчанию, используемую, когда tab_id опущен в вызовах инструментов, и при необходимости выводит её на передний план.

• Интерфейс, удобный для LLM: Инструменты жизненного цикла (open_instance, close_instance, open_tab, list_tabs, switch_tab, close_tab) возвращают структурированный JSON, поэтому агенты могут выстраивать цепочки вызовов без regex-разбора текста, а их описания следуют стандартному шаблону MCP (побочные эффекты, предварительные условия, возвращаемые значения, альтернативы), чтобы модели правильно их ранжировали.

• Маршрутизация по целевой вкладке (новое): Все инструменты, работающие с вкладками, принимают необязательный параметр tab_id для нацеливания команд и получения кэша состояния конкретной вкладки. Если параметр опущен, используется активная вкладка по умолчанию.

• Изолированные профили: По умолчанию запускает Chrome с новым временным профилем, гарантируя, что он не будет использовать файлы cookie, пароли или данные сеансов вашего основного браузера.

• Поддержка пользовательского профиля: При необходимости используйте --user-profile, чтобы задействовать существующие сеансы и файлы cookie вашего браузера.

• Динамическое управление портами: Автоматически определяет, используется ли порт по умолчанию (9222).

  • Если порт занят экземпляром Chrome, предоставляющим CDP (запущенным пользователем или другим управляемым экземпляром chrome-debug-mcp), он автоматически подключается к нему вместо запуска нового.

  • Управляемые профили эфемерны, поэтому не существует постоянного состояния на порт; второй сервер, использующий тот же порт, просто разделяет тот же браузер (и никогда не убивает подключённый экземпляр).

• Поддержка Docker и headless-режима: Полная совместимость с окружениями Docker. Используйте флаг --headless, чтобы запускать Chrome без графического интерфейса внутри контейнеров.

• Удалённое подключение / подключение к хосту: Используйте аргумент --host, чтобы подключиться к экземпляру Chrome, работающему на другой машине или на хостовой машине (например, --host host.docker.internal из контейнера).

• Необязательная инфопанель автоматизации: Добавьте флаг --enable-automation, чтобы явно показывать встроенное сообщение «Chrome управляется автоматизированным тестовым ПО». По умолчанию эта функция отключена для более незаметного взаимодействия.

• Поддержка прокси: restart_chrome теперь принимает необязательный аргумент proxy_server для запуска Chrome с маршрутизацией трафика через прокси.

• Автозапуск: Автоматически определяет, запущен ли Chrome на указанном порту. Если нет, запускает новый экземпляр с необходимыми флагами.

• restart_chrome: Перезапускает управляемый экземпляр Chrome.

• Пресеты возможностей: restart_chrome принимает необязательный массив features, чтобы клиент мог подключать дополнительные возможности браузера при каждом перезапуске. Это закрытый набор — произвольные флаги Chrome намеренно не принимаются, чтобы инструмент не стал точкой внедрения командной строки:

  • WEB_MCP — включает экспериментальную поверхность WebMCP (--enable-features=WebMCPTesting, --categoryExperimentalWebmcp=true) для сайтов, предоставляющих инструменты браузеру.

  • WEBGL_SOFTWARE — принудительно включает программный WebGL через SwiftShader (--use-gl=angle, --use-angle=swiftshader, --enable-unsafe-swiftshader) для сред без GPU, например контейнеров.

  Пресеты применяются к экземпляру, запущенному этим вызовом; последующий restart_chrome без features сбрасывает их, аналогично поведению proxy_server.

• stop_chrome: Корректно завершает управляемый экземпляр Chrome (SIGTERM/SIGINT с запасным вариантом SIGKILL).

• Надёжный жизненный цикл: Исправлены проблемы с зависшими процессами Chrome. Эфемерные профили удаляются при остановке, а cdp-browser-lite вычищает осиротевшие каталоги профилей, оставшиеся после аварийного завершения; всплывающее сообщение «Chrome не был завершён корректно» подавляется с помощью флагов запуска и правки профиля.

• ⚠️ Изменение поведения: Управляемые экземпляры Chrome теперь завершаются при выходе процесса MCP-сервера (включая сбои). Раньше управляемый Chrome переживал сбой сервера и повторно подключался при перезапуске; теперь он завершается. Подключённые (запущенные пользователем) экземпляры Chrome не завершаются никогда.

🔐 Аутентификация через прокси

• enable_proxy_auth: Автоматически обрабатывает запросы аутентификации прокси, подключаясь к домену Fetch CDP и передавая предоставленные пользователем учётные данные (имя пользователя и пароль).

• Улучшения надёжности: Теперь включает 30-секундный таймаут для медленных резидентных прокси и по умолчанию перехватывает только запросы Document, чтобы не нарушать фоновые запросы.

• Предварительный прогрев: Автоматически переходит на prewarm_url (по умолчанию http://api.ipify.org?format=json), чтобы надёжно установить прокси-туннель перед основной задачей навигации. При желании можно ограничить перехват конкретным resource_type.

🖱️ Пользовательский ввод

• click_element: Имитирует нативный щелчок мыши по конкретному элементу с помощью CSS-селектора. Вычисляет центральные координаты элемента и напрямую отправляет события мыши CDP.

• fill_input: Заполняет поле ввода в DOM указанным текстом. Фокусирует элемент через CSS-селектор, а затем использует нативный CDP Input.insertText.

• scroll: Прокручивает страницу на пиксели, высоты окна просмотра (страницы) или до конкретного элемента. Необходим для взаимодействия с лениво загружаемым контентом или бесконечной прокруткой.

📡 Инспекция сети

• get_network_logs: Получение перехваченных сетевых запросов (REST/HTTP) и кадров WebSocket.

• Расширенная фильтрация: Фильтрация журналов по URL, типу ресурса, направлению WebSocket или содержимому полезной нагрузки.

• Просмотр полезной нагрузки: Доступ к полным заголовкам запросов/ответов, телам REST-ответов и кадрам WebSocket.

• Оптимизация контекста: Необязательный «режим сводки», чтобы не переполнять контекстное окно LLM.

🪵 Консоль и ошибки

• get_console_logs: Получение журналов консоли из браузера. Включает вызовы console.log/warn/error, исключения и сетевые ошибки. Важно для устранения неполадок в скриптах страниц и ошибках. Включает необязательную фильтрацию по уровню журнала и флаг clear для эффективного управления состоянием.

⚡ Производительность и профилирование

• get_performance_metrics: Получение показателей производительности браузера во время выполнения (например, размер JS-кучи, узлы DOM, длительность компоновки). Полезно для быстрого снимка памяти страницы и вычислительных затрат.

• profile_page_performance: Запись и анализ трассировки производительности страницы. Автоматически вычисляет Core Web Vitals (FCP, LCP, DCL, Load) и определяет самые длинные Long Tasks (блокирующие операции главного потока). При желании можно перезагрузить страницу с отключённым кэшем, чтобы имитировать холодный старт.

🌐 Управление страницей и средой выполнения

• capture_screenshot: Делает снимок экрана текущей страницы (или полного макета страницы) и возвращает его LLM-клиенту в виде блока изображения в кодировке base64.

• navigate: Переходит на указанный URL в активной вкладке.

• reload: Перезагружает текущую страницу.

• inspect_dom: Получает весь HTML или интеллектуальный фрагмент вокруг поискового запроса.

  • Поиск по контексту: Ищет конкретный текст и возвращает настраиваемое количество символов вокруг него.

  • Эффективность токенов: Значительно сокращает использование контекстного окна для больших страниц.

• evaluate_js: Выполняет произвольное JavaScript-выражение глобально в контексте страницы.

🐞 Живая отладка и управление выполнением

• pause_on_load: Включает отладчик и запускает перезагрузку страницы, приостанавливая выполнение на самой первой разобранной инструкции скрипта.

• search_scripts: Выполняет поиск по всем разобранным контекстам скриптов для точного определения строк и колонок для точек останова.

• set_breakpoint: Устанавливает точную точку останова JS с помощью script_id, url или точного script_hash.

• evaluate_on_call_frame: Вычисляет JavaScript-выражение непосредственно внутри локальной области видимости текущего приостановленного кадра вызова отладчика.

• step_over: Перешагивает следующую строку выражения.

• resume: Снимает паузу и возобновляет выполнение.

• remove_breakpoint: Удаляет ранее установленную точку останова.

🧩 WebMCP (инструменты, доступные на странице) Требует перезапуска Chrome с пресетом возможностей WEB_MCP (см. restart_chrome).

• webmcp_list_tools: Перечисляет инструменты, которые текущая страница предоставляет браузеру (имя, описание, inputSchema, frameId).

• webmcp_invoke_tool: Вызывает инструмент страницы по имени. input — это строка JSON-объекта (например, "{}" или "{\"product\":\"knot\"}"), соответствующая inputSchema инструмента. Блокирует выполнение до 30 секунд в ожидании результата.

• webmcp_get_invocation: Возвращает статус (Pending/Completed/Error/Canceled) и результат вызова по invocationId — без блокировки.

• webmcp_list_invocations: Перечисляет все вызовы в сессии с их статусами, с необязательным фильтром по status.

  ⚠️ Диалоги согласия: инструменты страницы с побочными эффектами (запись в буфер обмена, отправка форм…) могут показывать диалог подтверждения на странице, по которому должен кликнуть человек. В этом случае webmcp_invoke_tool возвращает ошибку тайм-аута, содержащую invocationId — вызов остаётся в статусе Pending (он НЕ отменяется), поэтому вы можете опрашивать его с помощью webmcp_get_invocation после того, как пользователь одобрит или отклонит его.

🧪 Стабильность и надёжность

• Обширное модульное тестирование: Комплексный набор тестов, обеспечивающий надёжность обработки событий и десериализации инструментов, особенно в области debugger.

• Тесты без побочных эффектов: Все модульные тесты спроектированы так, чтобы выполняться изолированно, без запуска реальных экземпляров Chrome или изменения файловой системы.

• Внутренний рефакторинг: Разделение основной логики через трейты и внедрение зависимостей для обеспечения долгосрочной поддерживаемости.

Related MCP server: chrome-devtools-mcp

⚙️ Конфигурация

По умолчанию MCP Server находит исполняемый файл Chrome с помощью кроссплатформенного поиска cdp-browser-lite: сначала CHROME_PATH (абсолютный приоритет), затем стандартные бинарные файлы в вашем PATH (google-chrome, google-chrome-stable, chromium, chromium-browser), затем расположения, специфичные для ОС (/Applications/Google Chrome.app/... на macOS, каталог установки chrome.exe на Windows, /usr/bin/google-chrome, /opt/google/chrome/chrome и /snap/bin/chromium на Linux). Это строгое надмножество путей, которые сервер ранее задавал жёстко.

Аргументы:

• --local: Ограничивает навигацию только локальными адресами (localhost, 127.0.0.1, 192.168.x.x или *.local). Настоятельно рекомендуется для безопасности.

• --headless: Запускает Chrome в безголовом режиме (без GUI). Необходим для Docker или серверных сред.

• --user-profile: Использовать системный профиль пользователя по умолчанию (сессии, куки и т.д.) вместо нового. Это полезно для избежания повторных входов в систему во время исследовательских сессий.

• --host: Указывает целевой хост для экземпляра Chrome (по умолчанию: 127.0.0.1). Используйте host.docker.internal для подключения к хост-машине из контейнера.

• --port: Указывает порт удалённой отладки (по умолчанию: 9222).

• --enable-automation: Включает инфобар «управляется автоматическим программным обеспечением».

• --max-instances: Ограничивает максимальное количество одновременных экземпляров Chrome (по умолчанию: 8). Игнорируется, если задан --user-profile.

Переменные окружения:

• CHROME_PATH: Явно укажите путь к исполняемому файлу Chrome.

🐳 Docker и безголовый режим (v1.0.0)

chrome-debug-mcp полностью готов к работе в контейнерах. Это открывает несколько мощных сценариев использования для LLM:

1. Облачное развёртывание (через Glama)

Самый простой способ использования этого сервера. Glama запускает Docker-контейнер с предустановленным Chrome. LLM получает немедленный доступ к браузеру в облаке без какой-либо локальной настройки.

2. Изолированное локальное использование

Запустите всё внутри Docker, чтобы избежать установки Chrome или Rust на вашей хост-машине:

docker build -t chrome-mcp .
docker run -i --rm chrome-mcp --headless

3. Гибридный режим (контейнер управляет хостом)

MCP server работает внутри безопасного Docker-контейнера, но управляет экземпляром Chrome на вашем реальном рабочем столе. Это позволяет LLM помогать вам в вашей реальной сессии браузера:

1. Запустите ваш локальный Chrome с: --remote-debugging-port=9222

   • Примечание: Если в этом режиме вам нужна поддержка прокси, вы также должны запустить Chrome с флагом --proxy-server="http://your-proxy:port".

2. Запустите контейнер:

# On macOS/Windows
docker run -i --rm chrome-mcp --host host.docker.internal

🚀 Быстрый старт

Самый простой способ установить и запустить MCP Server нативно — через Cargo от Rust или загрузив предварительно скомпилированные бинарные файлы. Вам больше не нужно запускать Chrome вручную: MCP Server автоматически запустит видимый экземпляр Chrome с правильными флагами отладки.

1. Установка

Вариант A: Предварительно скомпилированные бинарные файлы (рекомендуется) Перейдите на страницу Releases и загрузите нативный исполняемый файл для вашей платформы (macOS, Windows, Linux). Мы предоставляем установщики .msi для Windows и shell-скрипты для UNIX-систем.

Вариант B: Установка через Cargo

cargo install --git https://github.com/raultov/chrome-debug-mcp

Вариант C: Установка через shell-скрипт (Unix)

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/raultov/chrome-debug-mcp/releases/latest/download/chrome-debug-mcp-installer.sh | sh

2. Настройка вашего MCP-клиента

Этот сервер полностью протестирован, и подтверждено, что он работает с Claude Code, agy и codex. Настройте вашего AI-клиента на запуск сервера, используя любой из следующих режимов.

Универсальная конфигурация (JSON)

Большинство MCP-клиентов (например, Claude Code или любая JSON-конфигурация) используют эту структуру. Вот три основных режима использования:

{
  "mcpServers": {
    "chrome-debug-mcp": {
      "command": "chrome-debug-mcp",
      "args": [],
      "env": {}
    },
    "chrome-docker": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "chrome-debug-mcp:v1.0.9", "--headless"]
    },
    "chrome-docker-hybrid": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--net=host",
        "chrome-debug-mcp:v1.0.9",
        "--host",
        "127.0.0.1"
      ]
    }
  }
}

Примечание: Режим chrome-docker-hybrid с использованием --net=host рекомендуется на Linux, чтобы позволить контейнеру получить доступ к вашему локальному экземпляру Chrome на 127.0.0.1.

Claude Code

Чтобы добавить и активировать сервер в Claude Code:

claude mcp add chrome-debug-mcp chrome-debug-mcp

3. Использование

После подключения AI-агент автоматически запустит Chrome при выполнении первой команды. Браузер останется видимым, чтобы вы могли визуально отслеживать процесс отладки.

4. Сценарии работы агента и рекомендации по нескольким экземплярам

LLM могут управлять этим сервером, используя несколько оптимизированных паттернов:

A. Изолированные сценарии с несколькими экземплярами

При запуске автоматизированных сессий браузера вы можете запускать отдельные процессы Chrome, чтобы предотвратить загрязнение куки или конфликты вкладок:

1. Вызовите open_instance с label: "user-session-1" или необязательными конфигурациями прокси-сервера. Это вернёт уникальный instance_id (например, chrome-2).

2. Передавайте instance_id явно в последующие инструменты, такие как navigate, evaluate_js или webmcp_list_tools.

3. Освободите ресурсы с помощью close_instance после завершения.

B. Работа с WebMCP

Если вы переходите на страницу, поддерживающую WebMCP (например, https://www.knot.kz/#/agent-tools):

1. Инструменты, зарегистрированные веб-страницей, можно получить с помощью webmcp_list_tools.

2. По умолчанию WEB_MCP отключён в целях безопасности. Если список инструментов пуст, вызовите restart_chrome с features: ["WEB_MCP"], а затем reload.

3. Вызывайте инструменты страницы с помощью webmcp_invoke_tool, передавая входные JSON-аргументы. Если диалог согласия приостанавливает выполнение на веб-странице, инструмент завершится по тайм-ауту через 30 секунд, но вызов останется в статусе pending. Вы можете опросить его результат с помощью webmcp_get_invocation.

🛠 Компиляция (из исходного кода)

Если вы хотите скомпилировать из исходного кода:

git clone https://github.com/raultov/chrome-debug-mcp
cd chrome-debug-mcp
cargo build --release

Полученный бинарный файл будет находиться в target/release/chrome-debug-mcp. Этот проект использует cargo-dist для бесшовной кроссплатформенной нативной дистрибуции через GitHub Actions.

📖 Зачем нужен этот MCP Server?

Другие интеграционные серверы, такие как обёртки Puppeteer/Playwright, являются высокоуровневыми, тяжёлыми и обычно не способны предоставить настоящие, интерактивные пошаговые отладчики. Этот MCP server использует сырые CDP-сообщения, сопоставляя их 1:1 с инструментами LLM, что позволяет интеллектуальным агентам буквально перешагивать через JS, нативно читать переменные локальной области видимости, искать внутри контекстов компилятора V8 и точно понимать, почему скрипт падает.

📜 Лицензия

Этот проект лицензирован под MIT License. Подробнее см. в файле LICENSE.