MCP-сервер и CLI для браузера
Примечание к проекту : Эта реализация сервера MCP основана на основе браузера-использования/веб-пользователя . Основная логика автоматизации браузера и шаблоны конфигурации адаптированы из оригинального проекта.
Сервер автоматизации браузера на базе ИИ, реализующий протокол Model Context Protocol (MCP) для управления браузером на естественном языке и веб-исследований. Также предоставляет доступ CLI к своим основным функциям.
Функции
🧠 Интеграция MCP — полная реализа��ия протокола для связи с агентами ИИ.
🌐 Автоматизация браузера — навигация по страницам, заполнение форм, взаимодействие с элементами на естественном языке (инструмент
run_browser_agent
).👁️ Визуальное понимание — дополнительный анализ снимков экрана для обладателей степени магистра права с хорошим зрением.
🔄 Сохранение состояния — возможность управлять сеансом браузера сервера через несколько вызовов MCP или подключаться к браузеру пользователя.
🔌 Поддержка нескольких LLM — интеграция с OpenAI, Anthropic, Azure, DeepSeek, Google, Mistral, Ollama, OpenRouter, Alibaba, Moonshot, Unbound AI.
🔍 Deep Research Tool — специализированный инструмент для многоэтапного веб-исследования и создания отчетов (инструмент
run_deep_research
).⚙️ Конфигурация переменных среды — полностью настраивается с помощью переменных среды с использованием структурированной модели Pydantic.
🔗 Подключение CDP — возможность подключения и управления запущенным пользователем экземпляром Chrome/Chromium через протокол Chrome DevTools.
⌨️ Интерфейс командной строки — доступ к основным функциям агента (
run_browser_agent
,run_deep_research
) непосредственно из командной строки для тестирования и создания сценариев.
Быстрый старт
Основы
Установите UV — установщик Python с ракетным двигателем:
curl -LsSf https://astral.sh/uv/install.sh | sh
Получите браузеры Playwright (требуются для автоматизации):
uvx --from mcp-server-browser-use@latest python -m playwright install
Модели интеграции
Для клиентов MCP, таких как Claude Desktop, добавьте простую конфигурацию сервера:
Ключевая информация: Лучшие конфигурации получаются, если начинать с простого (Пример 1). Файл .env.example содержит все возможные циферблаты.
Инструменты МКП
Этот сервер предоставляет следующие инструменты через протокол контекста модели:
Синхронные инструменты (ожидание завершения)
run_browser_agent
Описание: Выполняет задачу автоматизации браузера на основе инструкций естественного языка и ждет ее завершения. Использует настройки из переменных среды
MCP_AGENT_TOOL_*
,MCP_LLM_*
иMCP_BROWSER_*
.Аргументы:
task
(строка, обязательно): Основная задача или цель.
Возвращает: (строка) Окончательный результат, извлеченный агентом, или сообщение об ошибке. История агента (JSON, необязательно GIF) сохраняется, если задано
MCP_AGENT_TOOL_HISTORY_PATH
.
run_deep_research
Описание: выполняет углубленное веб-исследование по теме, генерирует отчет и ждет завершения. Использует настройки из переменных среды
MCP_RESEARCH_TOOL_*
,MCP_LLM_*
иMCP_BROWSER_*
. Если заданMCP_RESEARCH_TOOL_SAVE_DIR
, выходные данные сохраняются в подкаталоге внутри него; в противном случае работает в режиме только памяти.Аргументы:
research_task
(строка, обязательно): Тема или вопрос исследования.max_parallel_browsers
(целое число, необязательное): переопределяетMCP_RESEARCH_TOOL_MAX_PARALLEL_BROWSERS
из среды.
Возвращает: (строка) Сгенерированный отчет об исследовании в формате Markdown, включая путь к файлу (если сохранен) или сообщение об ошибке.
Использование CLI
Этот пакет также предоставляет интерфейс командной строки mcp-browser-cli
для прямого тестирования и написания сценариев.
Глобальные параметры:
--env-file PATH, -e PATH
: Путь к файлу.env
для загрузки конфигураций.--log-level LEVEL, -l LEVEL
: Переопределить уровень ведения журнала (например,DEBUG
,INFO
).
Команды:
mcp-browser-cli run-browser-agent [OPTIONS] TASK
Описание: Запускает задачу агента браузера.
Аргументы:
TASK
(строка, обязательно): Основная задача для агента.
Пример:
mcp-browser-cli run-browser-agent "Go to example.com and find the title." -e .env
mcp-browser-cli run-deep-research [OPTIONS] RESEARCH_TASK
Описание: Проводит глубокие веб-исследования.
Аргументы:
RESEARCH_TASK
(строка, обязательно): Тема или вопрос для исследования.
Параметры:
--max-parallel-browsers INTEGER, -p INTEGER
: ПереопределитьMCP_RESEARCH_TOOL_MAX_PARALLEL_BROWSERS
.
Пример:
mcp-browser-cli run-deep-research "What are the latest advancements in AI-driven browser automation?" --max-parallel-browsers 5 -e .env
Все остальные конфигурации (ключи LLM, пути, настройки браузера) берутся из переменных среды (или указанного файла .env
), как подробно описано в разделе «Конфигурация».
Конфигурация (переменные среды)
Настройте сервер и CLI с помощью переменных окружения. Вы можете задать их в своей системе или поместить в файл .env
в корне проекта (используйте --env-file
для CLI). Переменные структурированы с помощью префиксов.
Группа переменных (префикс) | Пример переменной | Описание | Значение по умолчанию |
Основная степень магистра права (MCP_LLM_) | Настройки для основного LLM, используемого агентами. | ||
| Поставщик LLM. Варианты:
,
,
,
,
,
и т. д. |
| |
| Конкретное название модели для поставщика. |
| |
| Температура LLM (0,0-2,0). |
| |
| Необязательно: общее переопределение базового URL-адреса поставщика LLM. | Специфичный для поставщика | |
| Необязательно: универсальный ключ LLM API (имеет приоритет). | - | |
| Ключ API для OpenAI (если поставщик —
). | - | |
| API-ключ для Anthropic. | - | |
| API-ключ для Google AI (Gemini). | - | |
| Ключ API для Azure OpenAI. | - | |
| Требуется при использовании Azure. Ваша конечная точка ресурса Azure. | - | |
| URL-адрес конечной точки API Ollama. |
| |
| Размер контекстного окна для моделей Ollama. |
| |
Планировщик LLM (MCP_LLM_PLANNER_) | Необязательно: Настройки для отдельного LLM для планирования агента. По умолчанию используется Main LLM, если не задано. | ||
| Поставщик услуг LLM Planner. | Основной поставщик LLM | |
| Название модели Planner LLM. | Основная модель LLM | |
Браузер (MCP_BROWSER_) | Общие настройки браузера. | ||
| Запустить браузер без пользовательского интерфейса (общие настройки). |
| |
| Отключите функции безопасности браузера (общая настройка, используйте осторожно). |
| |
| Путь к исполняемому файлу Chrome/Chromium. | - | |
| Путь к каталогу пользовательских данных Chrome. | - | |
| Ширина окна браузера (в пикселях). |
| |
| Высота окна браузера (в пикселях). |
| |
| Подключитесь к браузеру пользователя через URL-адрес CDP. |
| |
| URL-адрес CDP (например,
). Требуется, если
. | - | |
| Оставлять управляемый сервером браузер открытым между вызовами MCP (если
). |
| |
| Необязательно: Каталог для сохранения файлов трассировки Playwright. Если не задано, трассировка в файл отключена. | (пусто, трассировка отключена) | |
Инструмент агента (MCP_AGENT_TOOL_) | Настройки для инструмента
. | ||
| Максимальное количество шагов за один запуск агента. |
| |
| Максимальное количество действий на шаг агента. |
| |
| Метод вызова инструмента ('auto', 'json_schema', 'function_calling'). |
| |
| Максимальное количество входных токенов для контекста LLM. |
| |
| Включить возможности зрения (анализ снимков экрана). |
| |
| Переопределить
для этого инструмента (true/false/пусто). | (использует общее) | |
| Переопределить
для этого инструмента (true/false/пусто). | (использует общее) | |
| Включить запись видео в режиме Playwright. |
| |
| Необязательно: Путь для сохранения записей. Если не задано, запись в файл отключена, даже если
. | (пусто, запись отключена) | |
| Необязательно: Каталог для сохранения файлов истории агента JSON. Если не задано, сохранение истории отключено. | (пусто, сохранение истории отключено) | |
Инструмент исследования (MCP_RESEARCH_TOOL_) | Настройки инструмента
. | ||
| Максимальное количество параллельных экземпляров браузера для глубоких исследований. |
| |
| Необязательно: Базовый каталог для сохранения исследовательских артефактов. Будет добавлен идентификатор задачи. Если не задано, работает в режиме только памяти. |
| |
Пути (MCP_PATHS_) | Общие настройки пути. | ||
| Необязательно: Каталог для загруженных файлов. Если не задано, постоянные загрузки по указанному пути отключены. | (пусто, загрузки отключены) | |
Сервер (MCP_SERVER_) | Настройки, специфичные для сервера. | ||
| Путь к файлу журнала сервера. Пустой для stdout. | (пусто, выводит на стандартный вывод) | |
| Уровень ведения журнала (
,
,
,
,
). |
| |
| Включить/отключить анонимную телеметрию (
/
). |
| |
| Необязательно: строка JSON для конфигурации клиента MCP, используемая внутренним контроллером. |
|
Поддерживаемые поставщики LLM ( openai
, azure_openai
, anthropic
, google
, mistral
, ollama
, deepseek
, openrouter
, alibaba
, moonshot
, unbound
(Полный список всех поддерживаемых переменных среды и их конкретных ключей/конечных точек поставщика см. в
Подключение к собственному браузеру (CDP)
Вместо того чтобы сервер запускал и управлял собственным экземпляром браузера, вы можете подключить его к браузеру Chrome/Chromium, который вы запускаете и управляете самостоятельно.
Шаги:
Запустите Chrome/Chromium с включенной удаленной отладкой: (команды для macOS, Linux, Windows перечислены ранее, например,
google-chrome --remote-debugging-port=9222
)Настройте переменные среды: установите следующие переменные среды:
MCP_BROWSER_USE_OWN_BROWSER=true MCP_BROWSER_CDP_URL=http://localhost:9222 # Use the same port # Optional: MCP_BROWSER_USER_DATA_DIR=/path/to/your/profileЗапустите сервер MCP или CLI: Запустите сервер (
uv run mcp-server-browser-use
) или CLI (mcp-browser-cli ...
) как обычно.
Важные соображения:
Браузер, запущенный с
--remote-debugging-port
должен оставаться открытым.Такие настройки, как
MCP_BROWSER_HEADLESS
иMCP_BROWSER_KEEP_OPEN
игнорируются, еслиMCP_BROWSER_USE_OWN_BROWSER=true
.
Разработка
Поиск неисправностей
Ошибка конфигурации при запуске : если приложение не запускается из-за ошибки об отсутствующем параметре, убедитесь, что все обязательные переменные среды (например,
MCP_RESEARCH_TOOL_SAVE_DIR
) правильно заданы в вашей среде или файле.env
.Конфликты браузеров : если CDP не используется (
MCP_BROWSER_USE_OWN_BROWSER=false
), убедитесь, что не запущены конфликтующие экземпляры Chrome с тем же каталогом пользовательских данных, если указанMCP_BROWSER_USER_DATA_DIR
.Проблемы с подключением CDP : Если используется
MCP_BROWSER_USE_OWN_BROWSER=true
:Убедитесь, что Chrome запущен с
--remote-debugging-port
.Убедитесь, что порт в
MCP_BROWSER_CDP_URL
совпадает.Проверьте брандмауэры и убедитесь, что браузер запущен.
Ошибки API : дважды проверьте ключи API (
MCP_LLM_<PROVIDER>_API_KEY
илиMCP_LLM_API_KEY
) и конечные точки (например,MCP_LLM_AZURE_OPENAI_ENDPOINT
для Azure).Проблемы со зрением : убедитесь, что
MCP_AGENT_TOOL_USE_VISION=true
и ваша степень магистра права поддерживает зрение.Проблемы с зависимостями : Запустите
uv sync
иuv run playwright install
.Проблемы с файлами/путями :
Если дополнительные функции, такие как сохранение истории, трассировка или загрузки, не работают, убедитесь, что установлены соответствующие переменные пути (
MCP_AGENT_TOOL_HISTORY_PATH
,MCP_BROWSER_TRACE_PATH
,MCP_PATHS_DOWNLOADS
) и у приложения есть разрешения на запись в эти расположения.Для более глубокого исследования убедитесь, что
MCP_RESEARCH_TOOL_SAVE_DIR
установлен в допустимом каталоге с возможностью записи.
Ведение журнала : Проверьте файл журнала (
MCP_SERVER_LOG_FILE
, если установлен) или вывод консоли. УвеличьтеMCP_SERVER_LOGGING_LEVEL
доDEBUG
для получения более подробной информации. Для CLI используйте--log-level DEBUG
.
Лицензия
MIT — подробности см. в разделе ЛИЦЕНЗИЯ .
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Tools
Облегчает автоматизацию браузера с помощью настраиваемых возможностей и агентских взаимодействий, интегрированных через библиотеку использования браузера.
- Функции
- Быстрый старт
- Инструменты МКП
- Использование CLI
- Конфигурация (переменные среды)
- Подключение к собственному браузеру (CDP)
- Разработка
- Поиск неисправностей
- Лицензия
Related Resources
Related MCP Servers
- AsecurityFlicenseAqualityEnables AI agents to interact with web browsers using natural language, featuring automated browsing, form filling, vision-based element detection, and structured JSON responses for systematic browser control.Last updated -55
- -securityFlicense-qualityEnables AI agents to control web browsers via a standardized interface for operations like launching, interacting with, and closing browsers.
- -securityFlicense-qualityEnables AI assistants to control a browser through a set of tools, allowing them to perform web automation tasks like navigation, typing, clicking, and taking screenshots.Last updated -
- -securityFlicense-qualityEnables AI assistants to control a browser through a set of tools, allowing them to perform web automation tasks like navigation, typing, clicking, and taking screenshots.Last updated -