MCP Browser Use

Чего можно достичь с помощью этого MCP

Этот проект направлен на то, чтобы дать ИИ-агентам возможность выполнять веб-задачи, автоматизацию браузера и парсинг с помощью протокола Model Context Protocol (MCP) и Selenium.

Особенность этого MCP заключается в том, что он может обрабатывать несколько агентов, получающих доступ к нескольким окнам браузера. Не нужно запускать несколько Docker-образов, виртуальных машин или компьютеров, чтобы иметь несколько агентов для парсинга. И при этом можно использовать один профиль браузера для всех агентов. У каждого агента будут свои окна, и они не будут мешать друг другу.

Это делает работу с несколькими агентами бесшовной: просто запустите столько агентов, сколько хотите, и все будет работать! Используйте два экземпляра Claude Code, один экземпляр Codex CLI, один экземпляр Gemini CLI и один экземпляр fast-agent — все на одном компьютере, все с использованием одного и того же профиля браузера, и все работают (более-менее) параллельно.

Наша миссия — позволить ИИ-агентам выполнять любые веб-задачи с минимальным участием человека — и все это на основе инструкций на естественном языке.

Related MCP server: Selenium MCP Server

Основные возможности

• Усечение HTML: MCP позволяет настроить усечение HTML-страниц. Другие MCP для парсинга могут перегружать ИИ снимками доступности или дампами HTML, которые больше контекстного окна. Этот MCP поможет вам управлять максимальным размером страницы, установив переменную окружения MCP_MAX_SNAPSHOT_CHARS.

• Несколько окон браузера и несколько агентов: Вы можете подключать несколько агентов к этому MCP независимо, без необходимости координации со стороны агентов. Каждый агент может работать с одним и тем же профилем браузера, что полезно, когда нужно сохранять авторизацию между агентами. Каждый агент получает свое собственное окно браузера, поэтому они не мешают друг другу. Использует TargetId протокола Chrome DevTools для идентификации окон браузера.

Известные ограничения

• Контекст Iframe: Многошаговые взаимодействия внутри iframe требуют указания iframe_selector для каждого действия. Контекст браузера сбрасывается после каждого вызова инструмента для надежности. Для рабочих процессов с iframe повторяйте параметр селектора iframe в каждом вызове click_element, fill_text или debug_element.

Конфигурация / Установка

1. Клонируйте и создайте виртуальное окружение

git clone https://github.com/janspoerer/mcp_browser_use.git
cd mcp_browser_use
python3 -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -r requirements.txt

2. Установите Chrome Beta

Мы рекомендуем использовать Chrome Beta (не ваш обычный Chrome), чтобы ИИ-агенты могли работать с удаленной отладкой, не мешая вашему повседневному просмотру веб-страниц.

macOS:

brew install --cask google-chrome-beta

Ubuntu / Debian:

wget -q -O - https://dl.google.com/linux/linux_signing_key.pub | sudo apt-key add -
echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" \
    | sudo tee /etc/apt/sources.list.d/google-chrome.list
sudo apt update && sudo apt install -y google-chrome-beta

Windows: Скачайте и установите Chrome Beta с google.com/chrome/beta.

После установки проверьте:

google-chrome-beta --version      # Linux
# or
"/Applications/Google Chrome Beta.app/Contents/MacOS/Google Chrome Beta" --version  # macOS

Серверы Linux без графического интерфейса — Xvfb (виртуальный дисплей)

Chrome требует дисплея. На серверах Linux без графического интерфейса (headless) используйте Xvfb:

sudo apt install -y xvfb

# Start a virtual display on screen :99
Xvfb :99 -screen 0 1920x1080x24 &

# Tell Chrome which display to use
export DISPLAY=:99

Добавьте export DISPLAY=:99 в ваш .bashrc или .profile, чтобы сделать это постоянным.

3. Настройка и запуск

• После установки Chrome Beta укажите путь к исполняемому файлу Chrome Beta в вашем .mcp.json, как описано в разделе «Конфигурация переменных окружения» ниже.

• Запустите сервер MCP (если вы не знаете, как это сделать, ознакомьтесь с разделом «Как использовать (этот) MCP» ниже).

Как использовать (этот) MCP

Пожалуйста, обратитесь к документации MCP на modelcontextprotocol.io.

Обратите внимание, что вам нужно будет установить все зависимости в среде Python, на которую указывает ваш файл конфигурации MCP. Например, если вы указываете на исполняемый файл python или python3, вы будете указывать на глобальную среду Python. Обычно предпочтительнее указывать на виртуальную среду, например:

/Users/yourname/code/mcp_browser_use/.venv/bin/python

Если вы клонировали этот репозиторий в свою локальную папку code, ваш файл конфигурации MCP должен выглядеть так:

{
    "mcpServers": {
        "mcp_browser_use": {
            "command": "/Users/janspoerer/code/mcp_browser_use/.venv/bin/python",
            "args": [
                "/Users/janspoerer/code/mcp_browser_use/mcp_browser_use"
            ]
        }
    }
}

и он будет находиться здесь (в macOS): /Users/janspoerer/Library/Application Support/Claude/claude_desktop_config.json.

Пожалуйста, обратитесь к requirements.txt, чтобы увидеть, какие зависимости вам нужно установить.

Перезапустите Claude, чтобы проверить, действительна ли конфигурация JSON. Claude укажет вам на журналы ошибок MCP, если что-то не так.

Если настройка прошла успешно, вы увидите маленький значок молотка в правом нижнем углу окна «New Chat» в Claude. Рядом с молотком будет указано количество функций, которые предоставляет MCP.

Нажмите на молоток, чтобы увидеть доступные инструменты.

Конфигурация переменных окружения

ВАЖНО: Определите все переменные окружения в файле .mcp.json в корне вашего проекта, а НЕ в файлах .env. Это обеспечивает единый источник истины без конфликтов.

Рекомендуемая конфигурация (Chrome Beta)

Добавьте переменные окружения в раздел env вашего файла .mcp.json:

{
  "mcpServers": {
    "mcp_browser_use": {
      "type": "stdio",
      "command": "/path/to/.venv/bin/python",
      "args": ["-m", "mcp_browser_use"],
      "env": {
        "BETA_PROFILE_NAME": "SeleniumProfile",
        "BETA_EXECUTABLE_PATH": "/Applications/Google Chrome Beta.app/Contents/MacOS/Google Chrome Beta",
        "BETA_PROFILE_USER_DATA_DIR": "/Users/yourname/Library/Application Support/Google/Chrome Beta",
        "CHROME_REMOTE_DEBUG_PORT": "9225",
        "MCP_HEADLESS": "0",
        "MCP_ENABLE_EXTENSIONS": "1",
        "MAX_SNAPSHOT_CHARS": "10000"
      }
    }
  }
}

Пример для Windows:

"env": {
  "BETA_PROFILE_NAME": "SeleniumProfile",
  "BETA_EXECUTABLE_PATH": "C:\\Program Files\\Google\\Chrome Beta\\Application\\chrome.exe",
  "BETA_PROFILE_USER_DATA_DIR": "C:\\Users\\yourname\\AppData\\Local\\Google\\Chrome Beta\\User Data",
  "CHROME_REMOTE_DEBUG_PORT": "9225",
  "MCP_HEADLESS": "0",
  "MCP_ENABLE_EXTENSIONS": "1"
}

Справочник переменных окружения

Почему стоит использовать Chrome Beta?

Использование Chrome Beta (или Canary) предотвращает конфликты с вашим обычным браузером Chrome:

• ИИ-агентам требуется, чтобы Chrome работал с включенной удаленной отладкой

• Ваш обычный экземпляр Chrome не может работать с удаленной отладкой

• Chrome Beta позволяет обоим сосуществовать в одной системе

Рекомендации по профилям

• Используйте выделенный профиль, например "SeleniumProfile" (НЕ "Default")

• Это предотвращает конфликты, если вы открываете Chrome Beta вручную

• Расширения и авторизации сохраняются в этом профиле между сессиями

• Каждый ИИ-агент получает свое собственное окно браузера, но использует общий профиль

Доступные инструменты

Отладка

Проверьте, запущен ли браузер, посетив этот URL в вашем основном браузере (не в автоматизированном браузере):

http://127.0.0.1:9223/json/version

Если браузер запущен, он отобразит что-то вроде этого:

{
   "Browser": "Chrome/140.0.7339.24",
   "Protocol-Version": "1.3",
   "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36",
   "V8-Version": "14.0.365.3",
   "WebKit-Version": "537.36 (@f8765868e23d9ee5209061fc999f6495c525cd13)",
   "webSocketDebuggerUrl": "ws://127.0.0.1:9223/devtools/browser/d8f511eb-947c-4eb1-833d-917212a92394"
}

Файлы блокировки и координация

Этот MCP использует файловую блокировку для координации нескольких агентов, обращающихся к одному и тому же профилю браузера. Все файлы блокировки хранятся в tmp/mcp_locks/ в корневом каталоге проекта для удобства проверки.

Типы файлов блокировки

Блокировка действия (<hash>.softlock.json и <hash>.softlock.mutex)

• Гарантирует, что только один агент может выполнять действия в браузере за раз

• TTL по умолчанию: 30 секунд (настраивается через MCP_ACTION_LOCK_TTL)

• Автоматически продлевается с помощью heartbeat, пока агент работает

• Агенты ждут до 60 секунд для получения блокировки (настраивается через MCP_ACTION_LOCK_WAIT)

Реестр окон (<hash>.window_registry.json)

• Отслеживает, какой агент владеет каким окном браузера

• Содержит: targetId, windowId, PID процесса, временную метку последнего heartbeat

• Используется для очистки «сирот»: автоматически закрывает окна от зависших/упавших агентов

• Порог устаревания: 5 минут (настраивается через MCP_WINDOW_REGISTRY_STALE_SECS)

Мьютекс запуска (<hash>.startup.mutex)

• Обеспечивает запуск одного экземпляра браузера на профиль

• Используется во время координации запуска начального процесса Chrome

Формат файла: <hash> — это SHA-256 хэш, полученный из user_data_dir и profile_name вашего профиля Chrome, что обеспечивает стабильную идентификацию между процессами.

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

Вы можете настроить поведение блокировки с помощью этих переменных окружения:

# Lock directory (default: <project_root>/tmp/mcp_locks/)
MCP_BROWSER_LOCK_DIR=/path/to/locks

# Action lock TTL in seconds (default: 30)
MCP_ACTION_LOCK_TTL=30

# Max wait time for action lock in seconds (default: 60)
MCP_ACTION_LOCK_WAIT=60

# Window registry stale threshold in seconds (default: 300)
MCP_WINDOW_REGISTRY_STALE_SECS=300

# File mutex stale threshold in seconds (default: 60)
MCP_FILE_MUTEX_STALE_SECS=60

Очистка «сиротских» окон

Когда агент запускает сессию браузера, он автоматически:

1. Проверяет реестр окон на наличие записей от мертвых процессов (PID больше не существует)

2. Проверяет наличие устаревших записей (нет heartbeat более 5 минут)

3. Закрывает «сиротские» окна через протокол Chrome DevTools

4. Очищает записи в реестре

Это гарантирует, что упавшие или завершенные агенты не оставят открытыми «зомби-окна» браузера.

Демонстрационное видео (YouTube)

Запуск тестов

Мы НЕ хотим использовать pytest-asyncio.

pip install -e ".[test]"`