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 ) непосредственно из командной строки для тестирования и создания сценариев.

Related MCP server: jev-browser

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

Основы

1. Установите UV — установщик Python с ракетным двигателем: curl -LsSf https://astral.sh/uv/install.sh | sh

2. Получите браузеры Playwright (требуются для автоматизации): uvx --from mcp-server-browser-use@latest python -m playwright install

Модели интеграции

Для клиентов MCP, таких как Claude Desktop, добавьте простую конфигурацию сервера:

// Example 1: One-Line Latest Version (Always Fresh)
"mcpServers": {
    "browser-use": {
      "command": "uvx",
      "args": ["mcp-server-browser-use@latest"],
      "env": {
        "MCP_LLM_GOOGLE_API_KEY": "YOUR_KEY_HERE_IF_USING_GOOGLE",
        "MCP_LLM_PROVIDER": "google",
        "MCP_LLM_MODEL_NAME": "gemini-2.5-flash-preview-04-17",
        "MCP_BROWSER_HEADLESS": "true",
      }
    }
}

// Example 2: Advanced Configuration with CDP
"mcpServers": {
    "browser-use": {
      "command": "uvx",
      "args": ["mcp-server-browser-use@latest"],
      "env": {
        "MCP_LLM_OPENROUTER_API_KEY": "YOUR_KEY_HERE_IF_USING_OPENROUTER",
        "MCP_LLM_PROVIDER": "openrouter",
        "MCP_LLM_MODEL_NAME": "anthropic/claude-3.5-haiku",
        "MCP_LLM_TEMPERATURE": "0.4",

        "MCP_BROWSER_HEADLESS": "false",
        "MCP_BROWSER_WINDOW_WIDTH": "1440",
        "MCP_BROWSER_WINDOW_HEIGHT": "1080",
        "MCP_AGENT_TOOL_USE_VISION": "true",

        "MCP_RESEARCH_TOOL_SAVE_DIR": "/path/to/your/research",
        "MCP_RESEARCH_TOOL_MAX_PARALLEL_BROWSERS": "5",

        "MCP_PATHS_DOWNLOADS": "/path/to/your/downloads",

        "MCP_BROWSER_USE_OWN_BROWSER": "true",
        "MCP_BROWSER_CDP_URL": "http://localhost:9222",

        "MCP_AGENT_TOOL_HISTORY_PATH": "/path/to/your/history",

        "MCP_SERVER_LOGGING_LEVEL": "DEBUG",
        "MCP_SERVER_LOG_FILE": "/path/to/your/log/mcp_server_browser_use.log",
      }
    }
}

// Example 3: Advanced Configuration with User Data and custom chrome path
"mcpServers": {
    "browser-use": {
      "command": "uvx",
      "args": ["mcp-server-browser-use@latest"],
      "env": {
        "MCP_LLM_OPENAI_API_KEY": "YOUR_KEY_HERE_IF_USING_OPENAI",
        "MCP_LLM_PROVIDER": "openai",
        "MCP_LLM_MODEL_NAME": "gpt-4.1-mini",
        "MCP_LLM_TEMPERATURE": "0.2",

        "MCP_BROWSER_HEADLESS": "false",

        "MCP_BROWSER_BINARY_PATH": "/path/to/your/chrome/binary",
        "MCP_BROWSER_USER_DATA_DIR": "/path/to/your/user/data",
        "MCP_BROWSER_DISABLE_SECURITY": "true",
        "MCP_BROWSER_KEEP_OPEN": "true",
        "MCP_BROWSER_TRACE_PATH": "/path/to/your/trace",

        "MCP_AGENT_TOOL_HISTORY_PATH": "/path/to/your/history",

        "MCP_SERVER_LOGGING_LEVEL": "DEBUG",
        "MCP_SERVER_LOG_FILE": "/path/to/your/log/mcp_server_browser_use.log",
      }
    }
}

// Example 4: Local Development Flow
"mcpServers": {
    "browser-use": {
      "command": "uv",
      "args": [
        "--directory",
        "/your/dev/path",
        "run",
        "mcp-server-browser-use"
      ],
      "env": {
        "MCP_LLM_OPENROUTER_API_KEY": "YOUR_KEY_HERE_IF_USING_OPENROUTER",
        "MCP_LLM_PROVIDER": "openrouter",
        "MCP_LLM_MODEL_NAME": "openai/gpt-4o-mini",
        "MCP_BROWSER_HEADLESS": "true",
      }
    }
}

Ключевая информация: Лучшие конфигурации получаются, если начинать с простого (Пример 1). Файл .env.example содержит все возможные циферблаты.

Инструменты МКП

Этот сервер предоставляет следующие инструменты через протокол контекста модели:

Синхронные инструменты (ожидание завершения)

1. run_browser_agent

   • Описание: Выполняет задачу автоматизации браузера на основе инструкций естественного языка и ждет ее завершения. Использует настройки из переменных среды MCP_AGENT_TOOL_* , MCP_LLM_* и MCP_BROWSER_* .

   • Аргументы:

     • task (строка, обязательно): Основная задача или цель.

   • Возвращает: (строка) Окончательный результат, извлеченный агентом, или сообщение об ошибке. История агента (JSON, необязательно GIF) сохраняется, если задано MCP_AGENT_TOOL_HISTORY_PATH .

2. 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 ).

Команды:

1. 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

2. 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). Переменные структурированы с помощью префиксов.

Поддерживаемые поставщики LLM ( MCP_LLM_PROVIDER ): openai , azure_openai , anthropic , google , mistral , ollama , deepseek , openrouter , alibaba , moonshot , unbound

(Полный список всех поддерживаемых переменных среды и их конкретных ключей/конечных точек поставщика см. в .env.example .)

Подключение к собственному браузеру (CDP)

Вместо того чтобы сервер запускал и управлял собственным экземпляром браузера, вы можете подключить его к браузеру Chrome/Chromium, который вы запускаете и управляете самостоятельно.

Шаги:

1. Запустите Chrome/Chromium с включенной удаленной отладкой: (команды для macOS, Linux, Windows перечислены ранее, например, google-chrome --remote-debugging-port=9222 )

2. Настройте переменные среды: установите следующие переменные среды:

   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

3. Запустите сервер 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 .

Разработка

# Install dev dependencies and sync project deps
uv sync --dev

# Install playwright browsers
uv run playwright install

# Run MCP server with debugger (Example connecting to own browser via CDP)
# 1. Launch Chrome: google-chrome --remote-debugging-port=9222 --user-data-dir="optional/path/to/user/profile"
# 2. Run inspector command with environment variables:
npx @modelcontextprotocol/inspector@latest \
  -e MCP_LLM_GOOGLE_API_KEY=$GOOGLE_API_KEY \
  -e MCP_LLM_PROVIDER=google \
  -e MCP_LLM_MODEL_NAME=gemini-2.5-flash-preview-04-17 \
  -e MCP_BROWSER_USE_OWN_BROWSER=true \
  -e MCP_BROWSER_CDP_URL=http://localhost:9222 \
  -e MCP_RESEARCH_TOOL_SAVE_DIR=./tmp/dev_research_output \
  uv --directory . run mcp-server-browser-use

# Note: Change timeout in inspector's config panel if needed (default is 10 seconds)

# Run CLI example
# Create a .env file with your settings (including MCP_RESEARCH_TOOL_SAVE_DIR) or use environment variables
uv run mcp-browser-cli -e .env run-browser-agent "What is the title of example.com?"
uv run mcp-browser-cli -e .env run-deep-research "What is the best material for a pan for everyday use on amateur kitchen and dishwasher?"

Поиск неисправностей

• Ошибка конфигурации при запуске : если приложение не запускается из-за ошибки об отсутствующем параметре, убедитесь, что все обязательные переменные среды (например, 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 — подробности см. в разделе ЛИЦЕНЗИЯ .