stealth-browser-mcp

Сервер MCP, который даёт ИИ-ассистенту настоящий браузер Chrome с сохранённой авторизацией.

Большинство инструментов автоматизации браузеров выдают модели свежий пустой браузер. Этот же использует постоянный профиль Chrome, поэтому вы один раз входите сами — проходя через всю требуемую сайтом 2FA, CAPTCHA и проверки устройства — а модель может продолжать использовать эту сессию в следующих запусках, так и не увидев ваш пароль.

Для сайтов, которые не терпят автоматизированного входа, предусмотрены два запасных пути: учётные данные, извлекаемые из связки ключей macOS в момент заполнения, и ключи доступа WebAuthn, воспроизводимые через виртуальный аутентификатор Chrome.

[!WARNING] Это мощный инструмент. Он даёт языковой модели управление браузером с вашими актуальными сессиями и способен вводить сохранённые пароли на страницы, которые модель выбирает сама. Прочитайте SECURITY.md и Ответственное использование, прежде чем направлять его на что-то, что вам дорого.

Содержание

• Как это работает

• Требования

• Установка

• Подключение к MCP-клиенту

• Первый вход

• Справочник инструментов

• Хранение учётных данных в связке ключей

• Ключи доступа

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

• Проверка маскировки

• Устранение неполадок

• Ответственное использование

• Лицензия

Related MCP server: agent-browser-mcp

Как это работает

        MCP client (Claude Code, Claude Desktop, Cursor, …)
                          │
                          │  JSON-RPC over stdio
                          ▼
              ┌───────────────────────────┐
              │   stealth-browser-mcp     │
              │   16 tools, one browser   │
              └─────┬───────────────┬─────┘
                    │               │
     credentials    │               │   CDP + Puppeteer
                    ▼               ▼
        ┌───────────────────┐   ┌───────────────────────┐
        │  macOS Keychain   │   │  Google Chrome        │
        │  stealth-mcp:*    │   │  + stealth plugin     │
        │  passwords,       │   │  + WebAuthn virtual   │
        │  passkey material │   │    authenticator      │
        └───────────────────┘   └───────────┬───────────┘
                                            │
                                            ▼
                              ┌─────────────────────────┐
                              │  Persistent profile dir │
                              │  cookies · localStorage │
                              │  IndexedDB · sessions   │
                              └─────────────────────────┘

Работу делают три части:

Постоянство. Chrome запускается против фиксированного userDataDir, а не временного. Достаточно один раз войти в интерактивном окне, и cookie переживают все последующие запуски — обычная причина нарушения автоматизации на реальных сайтах исчезает.

Маскировка. puppeteer-extra-plugin-stealth закрывает известные признаки автоматизации, а сервер добавляет ещё несколько: navigator.webdriver равняется undefined, window.chrome.runtime присутствует, убирается HeadlessChrome из User-Agents, а такжe выставляется --disable-blink-features=AutomationControlled. Клики водят мышью по траектории до точки с дрожащим смещением внутри элемента; ввод выполняется посимвольно с паузами в 30–100 мс.

Повторное использование сессии вместо её создания. Целевая архитектура — вообще избегать автоматизации входа. Автозаполнение из связки ключей и повторен иные passkeys существуют для тех случаев, где обойтись без этого нельзя.

Требования

• Node.js 18 или новее

• Google Chrome. Встроенный Chromium от Puppeteer тоже работает, но полноценная сборка Chrome заметно менее детектируема.

• macOS, если нужны возможности связки ключей и passkey. Всё остальное — навигация, извлечение данных, скриншоты, постоянный профиль — кросс-платформенно. Слой связки ключей вызывает /usr/bin/security и на других платформах работать не будет; браузерные инструменты его не трогают.

Установка

git clone https://github.com/lauyuen/stealth-browser-mcp.git
cd stealth-browser-mcp
npm install

При желании скопируйте пример файла окружения и отредактируйте:

cp .env.example .env

Проверьте, что браузер запускается и маскировки активны:

npm run check-stealth

Подключение к MCP-клиенту

Сервер общается по stdio. Укажите клиенту абсолютный путь к src/server.js.

Claude Code

claude mcp add stealth-browser -- node /absolute/path/to/stealth-browser-mcp/src/server.js

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "stealth-browser": {
      "command": "node",
      "args": ["/absolute/path/to/stealth-browser-mcp/src/server.js"]
    }
  }
}

Любой другой MCP-клиент — та же схема, плюс необязательное переопределение профиля:

{
  "mcpServers": {
    "stealth-browser": {
      "command": "node",
      "args": ["/absolute/path/to/stealth-browser-mcp/src/server.js"],
      "env": {
        "BROWSER_PROFILE_DIR": "/absolute/path/to/a/private/profile/dir"
      }
    }
  }
}

После этого перезапустите клиент. browser_status — самый быстрый способ убедиться,что соединение активно.

Первый вход

Прежде чем модель сможет использовать сайт, наполните профиль вручную:

npm run login -- https://example.com

Откроется видимое окно Chrome с тем же профилем, который будет использовать MCP-сервер. Войдите как обычно — менеджеры паролей, запросы 2FA, CAPTCHA, «запомнить это устройство», всё в этом же спектре. Когда закончите, нажмите Enter в терминале, и сессия сохранится на диск.

Каждый следующий запуск MCP наследует эту сессию. Повторяйте процедуру для каждого сайта. Сессии истекают по собственному расписанию сайта, поэтому повторяйте, когда сайт выписывает регистрацию от вас.

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

Навигация и взаимодействие

Чтение страницы

Сессия и аутентификация

Жизненный цикл браузера

Браузер по умолчанию запускается в headless-режиме и переиспользуется между вызовами. browser_open_interactive_window — единственный инструмент, который переводит его в окна.

Хранение учётных данных в связке ключей

Пароли живут в связке ключей macOS под приставкой stealth-mcp:, никогда — в файле репозитории и никогда — в контексте модели.

npm run keychain set github you@example.com     # prompts; input is not echoed
npm run keychain get github you@example.com     # confirms presence, prints length only
npm run keychain delete github you@example.com

Затем модель запускает вход, так и не узнав секрет:

// browser_autofill_login
{
  "service": "github",
  "account": "you@example.com",
  "usernameSelector": "#login_field",
  "passwordSelector": "#password",
  "submitSelector": "input[type='submit']"
}

service — любая метка, которую вы выберете; она должна совпасть между CLI, аргументом в вызове инструмента.

Вы также можете передать пароль в конце команды CLI для скриптов, но он попадёт в историю вашей оболочки и список процессов, поэтому команда делает вам об этом.

Ключи доступа

Chrome предоставляет WebAuthn виртуальный аутентификатор через протокол DevTools — программный аутентификатор, предназначенный для тестирования сценариев WebAuthn. Этот сервер управляет им и хранит материю ключей в связке ключей, чтобы она сохранялась между запусками.

Регистрация автоматизированного ключа доступа

1. Вызовите passkey_enable_virtual_authenticator без аргументов.

2. Перейдите к форме добавления «passkey» на сайте и завершите её. Виртуальный аутентификатор отвечает на вызов; системные обы при не появляются.

3. Вызовите passkey_save_registration, указав rpId сайта и вашу учётную запись.

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

passkey_enable_virtual_authenticator с rpId и account внедряет сохранённые учётные данные до перехода, и сайт выполняет вход без запроса.

[!CAUTION] Хранимый таким образом ключ доступа — это файл, а не аппаратный ключ. Его можно: вот свойства, которые настоящие passkeys и должны предотвращать. Используйте ключ такого для чисто автоматизированных passkeys. Не применяйте его для ключа доступа, защищающего почту, банк или другую информацию, потеря которой критична.

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

Все настройки — это переменные окружения, читаемые из окружения процесса или из .env. См. .env.example.

Флаги запуска Chrome и размер окна по умолчанию 1280×800 находятся в src/config.js. Некоторые флаги обменивают безопасность на совместимость — SECURITY.md объясняет, какие именно и почему вам может стоит их удалить.

Проверка маскировки

npm run check-stealth

Сообщает значения navigator.webdriver, window.chrome, window.chrome.runtime, количество плагинов, navigator.languages и фактический user agent, а затем выводит вычисленные пути к профилю и Chrome.

Для более жёсткой проверки направьте браузер на страницу fingerprinting — например bot.sannysoft.com или abrahamjuliot.github.io/creepjs — с помощью browser_navigate, а затем browser_screenshot.

Никакая stealth-настройка не является полностью необнаружимой. Хорошо защищённые сайты сочетают fingerprinting с поведенческим анализом, репутацией IP-адреса и историей аккаунта и всё равно распознают автоматизацию. Относитесь к этому как к «не срабатывает на очевидных проверках», а не как к невидимости.

Устранение неполадок

«Failed to launch the browser process» / профиль заблокирован. Chrome допускает только один процесс на каталог профиля. Закройте любой Chrome, который вы запускали вручную с тем же каталогом профиля. Сервер при запуске удаляет устаревшие файлы блокировки Singleton* и переподключается к работающему экземпляру через его порт DevTools, но работающий Chrome, которому принадлежит профиль, имеет приоритет.

Сайт завершает сеанс модели или блокирует её. Сохранённый сеанс истёк. Повторно запустите npm run login -- <url>.

Селекторы не совпадают. Вызовите browser_extract_html с узким селектором и дайте модели прочитать реальную разметку, а не гадать. Одностраничные приложения часто монтируют поля ввода с задержкой — сначала browser_wait_for.

Появляется CAPTCHA. Вызовите browser_open_interactive_window, решите её сами и продолжайте. Решение сохраняется в профиле.

Ошибки Keychain в Linux или Windows. Это ожидаемо — этот слой существует только в macOS. Инструменты браузера работают везде; инструменты для учётных данных и passkey — нет.

Ответственное использование

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

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

• Условия использования сайта. Многие из них прямо запрещают автоматизированный доступ. Обход защиты от ботов может нарушить договор, с которым вы согласились, а в некоторых юрисдикциях несанкционированный доступ влечёт уголовную ответственность. Возможность обойти защиту — это не разрешение.

• Согласие. Автоматизируйте аккаунты, которые принадлежат вам или на которые у вас есть письменное разрешение действовать. Чужие учётные данные в вашей Keychain — это не согласие.

• Нагрузка. Ограничивайте интенсивность запросов. Уважайте robots.txt, где это применимо. Автоматизация, которая обходится сайту в реальные деньги, — верный способ добиться запрета этой техники для всех.

• Чужие данные. Страницы, которые читает модель, передаются провайдеру вашего MCP-клиента. Не пропускайте через него личные данные третьих лиц.

Вклады, основная цель которых — обход защиты конкретного сайта, сбор учётных данных или масштабирование злоупотреблений, не будут приняты.

Лицензия

MIT © Yuen Lau