SeleniumBase MCP Server

Предоставляет автоматизацию браузера SeleniumBase в виде инструментов через Model Context Protocol, так что любой MCP-клиент (Claude Desktop, Claude Code и т.д.) может управлять реальным браузером.

В этой папке есть три варианта сервера:

Во всех трёх по умолчанию headless=False — окно браузера видно, если только не передать headless=True при запуске сессии.

Укажите в конфигурации MCP-клиента тот *_server.py, который подходит под задачу (см. шаг 3 ниже), — или зарегистрируйте все три под разными именами.

1. Установка

(Требуются Python 3.10+ и uv)

git clone https://github.com/seleniumbase/seleniumbase-mcp.git
cd seleniumbase-mcp
uv sync

uv sync читает pyproject.toml, создаёт .venv/ в этой папке и устанавливает две зависимости (mcp[cli], seleniumbase) вместе с самим проектом — а он регистрирует три консольные команды через [project.scripts]:

• seleniumbase-driver

• seleniumbase-cdp

• seleniumbase-sb

Каждая просто вызывает функцию main() соответствующего файла сервера (mcp.run(transport="stdio")). Именно поэтому uv run <name> — без пути к python, без пути к venv, без пути к скрипту — работает как команда MCP-клиента на шагах 3 и 4 ниже.

# SeleniumBase's Driver() and SB() formats need a browser driver downloaded:
uv run seleniumbase get chromedriver
# (Not needed for the "seleniumbase-cdp" Pure CDP Mode MCP Server,
#  which doesn't use WebDriver at all.)

(Нет uv? Подойдёт и обычный python3 -m venv venv && pip install -e . — просто замените uv run <name> на python <script>.py во всех примерах ниже и используйте абсолютные пути venv/bin/python + путь к скрипту в конфигурации MCP-клиента вместо вариантов без путей.)

Related MCP server: gotham-browser

2. Попробуйте автономно (необязательная проверка)

uv run mcp dev cdp_server.py

Это открывает MCP Inspector для MCP-сервера SeleniumBase в режиме «Pure CDP Mode», где можно проверять команды («Tools»). Ctrl+C для выхода. Настоящая проверка — подключение к клиенту (следующий шаг).

3. Подключение к Claude Desktop

Claude Desktop запускается не из «проектной» директории, как Claude Code, поэтому голый uv run <name> не гарантированно найдёт этот репозиторий. Есть два способа получить стабильную конфигурацию:

Вариант A — глобальная установка (рекомендуется, вообще без путей):

uv tool install .          # from inside the repo, installs the 3 commands globally

Это навсегда добавляет seleniumbase-driver/seleniumbase-cdp/seleniumbase-sb в ваш PATH (один раз выполните uv tool ensurepath, если он предупредит, что его bin-каталог ещё не в PATH). Тогда claude_desktop_config.json может быть просто:

{
  "mcpServers": {
    "seleniumbase-cdp": { "command": "seleniumbase-cdp" },
    "seleniumbase-driver": { "command": "seleniumbase-driver" },
    "seleniumbase-sb": { "command": "seleniumbase-sb" }
  }
}

Вариант B — указать uv на репозиторий напрямую (один абсолютный путь, но не нужно искать venv/интерпретатор и не нужен отдельный шаг установки):

{
  "mcpServers": {
    "seleniumbase-cdp": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/seleniumbase-mcp", "run", "seleniumbase-cdp"]
    },
    "seleniumbase-driver": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/seleniumbase-mcp", "run", "seleniumbase-driver"]
    },
    "seleniumbase-sb": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/seleniumbase-mcp", "run", "seleniumbase-sb"]
    }
  }
}

Расположение claude_desktop_config.json зависит от вашей системы:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Перезапустите Claude Desktop. Вы должны увидеть значок инструментов 🔨, указывающий на подключённые серверы, с доступными инструментами вроде start_browser, navigate, click и т.д. Оставляйте только те записи, которые действительно нужны, — три отдельных сервера автоматизации браузера это много, если нужен только один.

4. Подключение к Claude Code

.mcp.json этого репозитория уже добавлен в git и готов к использованию как есть — правка путей не требуется, потому что uv run <name> находит этот проект по pyproject.toml в текущей директории:

{
  "mcpServers": {
    "seleniumbase-cdp": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "seleniumbase-cdp"]
    },
    "seleniumbase-driver": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "seleniumbase-driver"]
    },
    "seleniumbase-sb": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "seleniumbase-sb"]
    }
  }
}

Claude Code автоматически загружает .mcp.json из директории, в которой вы запускаете claude, так что пока вы запускаете claude внутри этого репозитория (или его клона), всё работает — одинаково для каждого коллеги, клонирующего репозиторий, без каких-либо правок под конкретную машину.

Если вы предпочитаете зарегистрировать серверы вручную, а не полагаться на .mcp.json:

claude mcp add seleniumbase-cdp -- uv run seleniumbase-cdp
claude mcp add seleniumbase-driver -- uv run seleniumbase-driver
claude mcp add seleniumbase-sb -- uv run seleniumbase-sb

(запускайте из директории репозитория по той же причине, что и выше.)

Доступные инструменты (driver_server.py)

Заметки по дизайну / что адаптировать под ваш сценарий

• Единая глобальная сессия. Каждый сервер одновременно держит одну сессию браузера. Это соответствует тому, как обычно запускаются MCP-серверы (один процесс на одно клиентское подключение), и сохраняет простоту набора инструментов. Если нужны несколько параллельных вкладок/сессий браузера, придётся расширить это до словаря именованных сессий и добавить параметр session_id в каждый инструмент.

• Блокирующие вызовы. Вызовы SeleniumBase синхронны и блокируют сервер, пока загружается страница или ожидается элемент. Для локального инструмента одного пользователя это нормально; для многоклиентского сервера их стоит запускать в пуле потоков через asyncio.to_thread.

• Headless против Headed. По умолчанию используется headed (headless=False), чтобы вы могли видеть работу браузера и чтобы сайты, блокирующие headless Chrome, продолжали работать. Передавайте headless=True для фонового/серверного использования после того, как подтвердите, что сценарий работает. uc=True в sb_server.py (undetected-chromedriver) также помогает против барьеров бот-защиты.

Расширение

Добавить инструмент — значит просто добавить функцию, декорированную @mcp.tool(), которая вызывает соответствующий метод SeleniumBase. У SeleniumBase есть методы для загрузки файлов, наведения курсора, работы с алертами, сетевыми условиями и многое другое, что пока не обёрнуто выше.

cdp_server.py — Pure CDP Mode

Обёртка над seleniumbase.sb_cdp.Chrome — самым скрытным режимом SeleniumBase: браузер управляется целиком через Chrome DevTools Protocol, без WebDriver в цепочке вообще. Справочник: cdp_mode_methods.md.

Группы инструментов

Заметки по дизайну для CDP

• Элементы не передаются по проводу как дескрипторы. В нативном режиме CDP find_element() возвращает живой объект с собственными методами (el.click(), el.get_html(), ...). Инструменты MCP могут возвращать только JSON-сериализуемые данные, поэтому find_element_info/find_all_info немедленно превращают элемент в простой словарь (tag_name, text, html), а не возвращают дескриптор, у которого можно было бы вызывать методы. Если нужно выполнить действие с одним из нескольких совпадений, используйте click_nth_element (действует по позиции), а не «найти, затем кликнуть» как два отдельных шага.

• Решение капчи не универсально. solve_captcha обрабатывает поддерживаемые типы вызовов (например, Cloudflare Turnstile в демо-приложении SeleniumBase); это не гарантированный обход произвольных CAPTCHA.

• Завершение сессии. sb.quit() (используется в close_browser) — это документированный способ завершить сессию; браузер также автоматически закрывается, если процесс завершится без него.

• Не обёрнуто: методы gui_* на основе PyAutoGUI (исключены осознанно — см. общие заметки по дизайну выше), низкоуровневая внутренняя обвязка (get_websocket_url, add_handler, выдача разрешений, сырые get_document/get_flattened_document), а также точные псевдонимы методов (open/goto вместо get) были опущены, чтобы держать набор инструментов сфокусированным — добавьте их тем же способом, что и любой другой инструмент, если они вам нужны.

sb_server.py — SB() без оператора with

Обёртка над seleniumbase.SB(), который обычно используется как контекстный менеджер:

with SB(uc=True) as sb:
    sb.goto(...)

Вызовы инструментов MCP-сервера происходят по одному за раз, в отдельных функциональных вызовах — здесь нет единого вложенного блока, вокруг которого можно написать with — поэтому этот сервер вызывает протокол контекстного менеджера вручную:

sb_context = SB(**kwargs)
sb = sb_context.__enter__()   # in start_browser
...
sb_context.__exit__(None, None, None)   # in close_browser

sb — это экземпляр BaseCase, самый широкий API SeleniumBase — надмножество того, что предоставляет Driver (в driver_server.py), плюс stealth-хелперы UC Mode и несколько дополнений, которых нет в driver_server.py/cdp_server.py. Этот сервер фокусируется на этих дополнениях, вместо того чтобы повторно оборачивать всё уже покрытое:

Плюс тот же базовый набор инструментов для навигации/взаимодействия/ожидания/ утверждений/cookie/прокрутки/вкладок/вывода, что и у двух других серверов, вызываемый через методы BaseCase (например, sb.goto, sb.click, sb.assert_element), а не через методы Driver или CDP.

Особые замечания для SB()

• UC Mode (stealth-режим) требует uc=True при запуске. Передайте его в start_browser заранее, если он вам понадобится.

• activate_cdp_mode не запускает новую сессию. Он переключает существующую сессию sb в Pure CDP для последующих действий — это усиление в середине потока, а не новый браузер.