agent-browser-mcp

MCP-сервис, позволяющий вашему агенту напрямую управлять «реальным Chrome, который вы используете».

Это не песочный браузер и не простой веб-скрейпер, а подключение к уже открытому на вашем компьютере Chrome, которое сохраняет:

Статус входа
Cookies
Открытые вкладки
Реальный контекст страницы

Подходит для таких сценариев:

Позволить Hermes напрямую читать ваши страницы в Xiaohongshu, системы администрирования, базы знаний и панели управления.
Автоматизация сайтов, на которых вы уже авторизованы, вместо повторного входа в «чистый» браузер.
Переключение на CDP / реальное управление мышью и клавиатурой, когда обычная автоматизация браузера работает нестабильно.
Объединение в одном MCP-инструменте: сканирование страниц, выполнение JS, управление через CDP, скриншоты, физический ввод.

Краткое описание:

Это проект, который упаковывает «автоматизацию реального браузера» в стандартный MCP, позволяя агенту не ограничиваться песочницей, а по-настоящему войти в ваш повседневный рабочий процесс в браузере.

Обзор основных возможностей

Обнаружение и переключение вкладок реального Chrome
Сканирование страниц и упрощенное извлечение контента
Выполнение JavaScript на странице
Выполнение отдельных команд или пакетных вызовов через нативный CDP
Скриншоты страниц / скриншоты рабочего стола
Чтение Cookies
Перемещение мыши, клики, перетаскивание
Ввод с клавиатуры и горячие клавиши

Если вы хотите, чтобы MCP-клиенты, такие как Hermes, Claude Desktop или Cursor, напрямую управляли вашим реальным локальным браузером, этот проект создан именно для этого.

Что умеет этот MCP

Этот проект упаковывает возможности автоматизации реального браузера в стандартные инструменты MCP, включая:

1. Вкладки браузера и навигация

Просмотр текущих подключенных вкладок
Переключение на указанную вкладку
Открытие URL в текущей вкладке
Открытие новой вкладки

2. Чтение страниц

Сканирование содержимого текущей страницы
Извлечение упрощенного HTML / текста
Подходит для чтения лент новостей, списков постов, страниц результатов поиска

3. Выполнение на странице и управление через CDP

Выполнение произвольного JavaScript на странице
Прямой вызов протокола Chrome DevTools (CDP)
Поддержка отдельных и пакетных команд
Может использоваться для скриншотов, запросов DOM, кликов, загрузки файлов и других сложных операций

4. Возможности скриншотов

Скриншот страницы (через CDP)
Скриншот рабочего стола (для помощи в реальных операциях на рабочем столе)

5. Реальный физический ввод

Перемещение мыши
Клик мышью
Перетаскивание мышью
Ввод с клавиатуры
Отправка горячих клавиш

Эти возможности отлично подходят для работы с:

Сайтами, где необходимо сохранять статус входа
Сайтами, которые легко блокируют обычные инструменты автоматизации браузера
Сценариями, требующими реальных кликов / реального ввода с клавиатуры
Сценариями, требующими чтения сложной структуры страниц

Для каких сценариев подходит

Например:

Использование Hermes для чтения вашей текущей ленты рекомендаций в Xiaohongshu
Открытие страницы администрирования в реальном браузере и извлечение информации
Вызов CDP для создания скриншота страницы
Возврат к реальному управлению мышью/клавиатурой, когда JS на странице недостаточно
Позволить агенту напрямую управлять сайтами, на которых вы уже вошли, вместо повторного входа в «чистый» браузер

Принцип работы

Проект состоит из трех уровней:

Расширение Chrome

Внедряется в реальные веб-страницы
Получает доступ к tabs / cookies / debugger / management через Chrome API
Обменивается данными с локальным мостовым сервисом

Локальный мост TMWebDriver

Слушает по умолчанию:
- WebSocket: 127.0.0.1:18765
- HTTP: 127.0.0.1:18766
Отвечает за подключение расширения, поддержку сеансов и пересылку результатов выполнения

MCP-сервис

Предоставляет возможности браузера в виде инструментов MCP
Для прямого вызова клиентами, такими как Hermes, Claude Desktop, Cursor

Основные инструменты

Текущие основные инструменты MCP включают:

Браузер/Вкладки

get_setup_status
list_tabs
switch_tab
open_url
open_new_tab
extension_path
list_extensions

Чтение/выполнение на странице

scan_page
execute_js

CDP и скриншоты

cdp_command
cdp_batch
get_cookies
capture_page_screenshot
capture_desktop_screenshot

Физический ввод

mouse_move
mouse_click
mouse_drag
type_text
hotkey
pointer_info

Требования к установке

Рекомендуемая среда:

macOS или Windows
Python 3.10+
Google Chrome
Любой клиент с поддержкой MCP, например:
- Hermes Agent
- Claude Desktop
- Cursor

Установка

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

cd agent-browser-mcp
pip install -e .

Если вы хотите сначала собрать wheel, а затем установить:

python -m pip install --upgrade build
python -m build
pip install dist/agent_browser_mcp-0.1.0-py3-none-any.whl

Инструменты командной строки

После установки будет доступен CLI:

agent-browser-mcp

У него есть несколько полезных подкоманд:

Вывод пути к расширению Chrome

agent-browser-mcp extension-path

Вывод фрагмента конфигурации Hermes

agent-browser-mcp print-hermes-config

Диагностика среды

agent-browser-mcp doctor

Эта команда выведет JSON, который поможет вам проверить:

Расположение каталога расширения
Сгенерирован ли config.js
Статус портов
Количество текущих подключенных вкладок
Рекомендации по следующим шагам

Установка расширения Chrome

Этот проект включает распакованное расширение Chrome, которое нужно загрузить вручную один раз.

Шаг 1: Получение пути к расширению

agent-browser-mcp extension-path

Шаг 2: Загрузка в Chrome

Откройте:

chrome://extensions

Затем:

Включите «Режим разработчика»
Нажмите «Загрузить распакованное расширение»
Выберите каталог, полученный на предыдущем шаге

Шаг 3: Откройте обычную веб-страницу

Обратите внимание: не оставайтесь на about:blank.

Пожалуйста, откройте в Chrome обычную веб-страницу, например:

https://www.baidu.com
https://www.xiaohongshu.com

В противном случае эффективный сеанс не будет установлен.

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

Добавьте следующий фрагмент в ~/.hermes/config.yaml:

mcp_servers:
  agent_browser:
    command: agent-browser-mcp
    timeout: 120
    connect_timeout: 60

В проекте также есть пример файла:

examples/hermes-config.yaml

После настройки перезапустите Hermes или перезагрузите MCP.

Проверить можно следующей командой:

hermes mcp list
hermes mcp test agent_browser

Если тест прошел успешно, Hermes сможет обнаружить и вызвать эти инструменты браузера.

Конфигурация Claude Desktop / Cursor

В репозитории также есть примеры:

examples/claude-desktop-config.json
examples/cursor-mcp.json

Структура конфигурации очень проста, суть заключается в:

{
  "mcpServers": {
    "agent_browser": {
      "command": "agent-browser-mcp",
      "args": []
    }
  }
}

Типичный рабочий процесс

Установка пакета Python
Загрузка расширения в Chrome
Открытие реальной веб-страницы
Подключение этого сервиса в MCP-клиенте
Начало вызова инструментов браузера

Например, агент может:

Открыть главную страницу Xiaohongshu
Прочитать ленту рекомендаций
Просканировать список постов
Сделать скриншот страницы через CDP
При необходимости выполнить реальные действия мышью/клавиатурой

Предупреждение о безопасности

Этот проект управляет вашим реальным браузером и реальным рабочим столом.

Это означает, что:

Перемещение мыши реально
Клики реальны
Ввод реален
Горячие клавиши реальны
Статус входа в браузере также реален

Пожалуйста, используйте это только в тех MCP-клиентах и средах агентов, которым вы доверяете.

Часто задаваемые вопросы

1. Hermes видит MCP-сервис, но не подключен ни к одной вкладке

Пожалуйста, проверьте:

Загружено ли расширение в chrome://extensions
Открыта ли в Chrome обычная веб-страница
Не остались ли вы на about:blank

Вы также можете запустить:

agent-browser-mcp doctor

2. `connected_tabs` равно 0

Обычно это происходит по одной из следующих причин:

Расширение не загрузилось успешно
В данный момент нет обычной веб-страницы
Расширение только что было перезагружено, страница еще не обновилась

Рекомендация:

Обновите текущую страницу
Откройте новый обычный URL
Запустите doctor еще раз

3. Физический ввод не работает на macOS

Пожалуйста, предоставьте терминалу / MCP-клиенту системные разрешения:

Универсальный доступ (Accessibility)
Запись экрана (если вам нужны скриншоты рабочего стола)

4. `hermes mcp test agent_browser` завершается ошибкой