Браузерный агент MCP

Агент браузера MCP

Функции

Расширенная автоматизация браузера
- Переходите к любому URL-адресу с помощью настраиваемых стратегий загрузки
- Делайте снимки экрана всей страницы или отдельных элементов
- Выполнять точные взаимодействия с DOM (щелчок, заполнение, выбор, наведение)
- Выполнение произвольного JavaScript в контексте браузера с записью журналов консоли
Мощный API-клиент
- Выполнение HTTP-запросов (GET, POST, PUT, PATCH, DELETE)
- Настройте заголовки запроса и содержимое тела
- Обработка данных ответа с использованием форматирования JSON
- Обработка ошибок с подробной обратной связью
Управление ресурсами MCP
- Доступ к журналам консоли браузера как к ресурсам
- Извлечение снимков экрана через интерфейс ресурсов MCP
- Постоянный сеанс с загруженным экземпляром браузера
Возможности ИИ-агента
- Объединяйте несколько операций браузера для решения сложных задач
- Следуйте многошаговым инструкциям с интеллектуальным устранением ошибок
- Автоматизация технических задач с помощью инструкций на естественном языке

Демо

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

00:00 - Поиск MCP в Google
Переход на домашнюю страницу Google и поиск по запросу «Model Context Protocol». Демонстрация Claude Desktop с использованием интеграции MCP для выполнения базового веб-поиска и обработки результатов.

00:33 - Снимок экрана
Создание снимка экрана результатов поиска с пользовательским именем файла и демонстрация его в Finder. Показывает, как Claude может захватывать и сохранять визуальный контент с веб-страниц во время автоматизации браузера.

01:00 - Поиск в Википедии
Переход на Wikipedia.org и поиск по запросу «Model Context Protocol». Демонстрирует способность Клода взаимодействовать с различными веб-сайтами и их поисковой функциональностью посредством интеграции MCP.

01:38 - Взаимодействие с выпадающим меню I
Переход на тестовый веб-сайт (the-internet.herokuapp.com/dropdown) и выбор «Варианта 1» из выпадающего меню. Демонстрирует способность Клода взаимодействовать с элементами формы и делать выбор.

01:56 - Взаимодействие с выпадающим меню II
Изменение выбора на «Вариант 2» из того же выпадающего меню. Демонстрирует способность Клода манипулировать одним и тем же элементом формы несколько раз и делать разный выбор.

02:09 - Заполнение формы входа
Переход на страницу входа (the-internet.herokuapp.com/login) и заполнение поля имени пользователя «tomsmith» и поля пароля «SuperSecretPassword!». Демонстрирует автоматизацию заполнения форм.

02:28 - Отправка логина
Отправка учетных данных для входа и завершение процесса аутентификации. Демонстрирует способность Клода инициировать отправку форм и перемещаться по многоэтапным процессам.

02:36 — Выполнение API-запроса
Выполнение запроса GET к конечной точке API JSONPlaceholder. Демонстрирует способность Клода делать прямые вызовы API и обрабатывать возвращаемые данные посредством интеграции MCP.

Требования

Node.js 16 или выше
Клод Десктоп
Зависимости драматурга

Поддержка браузера

npm init playwright@latest

Этот пакет включает Playwright и необходимые зависимости для запуска автоматизации браузера. При запуске npm install будут установлены требуемые зависимости Playwright. Пакет поддерживает следующие браузеры:

Хром (по умолчанию)
Firefox
Microsoft Эдж
WebKit (движок Safari)

При первом использовании типа браузера Playwright автоматически установит соответствующие драйверы браузера по мере необходимости. Вы также можете установить их вручную с помощью следующих команд:

npx playwright install chrome
npx playwright install firefox
npx playwright install webkit
npx playwright install msedge

Примечание о Safari : Playwright не предоставляет прямую поддержку браузеру Safari. Вместо этого он использует WebKit, который является движком браузера, на котором работает Safari.
Примечание о Edge : при выборе Edge в качестве типа браузера агент фактически запустит Microsoft Edge (не Chromium). Технически, в Playwright Edge запускается с использованием экземпляра браузера Chromium с параметром канала 'msedge', поскольку Microsoft Edge основан на Chromium.

Установка

Установка вручную

Клонируйте или загрузите этот репозиторий:

git clone https://github.com/imprvhub/mcp-browser-agent
cd mcp-browser-agent

Установить зависимости:

npm install

Создайте проект:

npm run build

Запуск сервера MCP

Существует два способа запуска сервера MCP:

Вариант 1: Запуск вручную

Откройте терминал или командную строку.
Перейдите в каталог проекта.
Запустите сервер напрямую:

node dist/index.js

Держите это окно терминала открытым при использовании Claude Desktop. Сервер будет работать, пока вы не закроете терминал.

Вариант 2: Автоматический запуск с помощью Claude Desktop (рекомендуется для регулярного использования)

Claude Desktop может автоматически запускать сервер MCP при необходимости. Чтобы настроить это:

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

Файл конфигурации Claude Desktop находится по адресу:

macOS : ~/Library/Application Support/Claude/claude_desktop_config.json
Windows : %APPDATA%\Claude\claude_desktop_config.json
Linux : ~/.config/Claude/claude_desktop_config.json

Отредактируйте этот файл, чтобы добавить конфигурацию Browser Agent MCP. Если файл не существует, создайте его:

{
  "mcpServers": {
    "browserAgent": {
      "command": "node",
      "args": ["ABSOLUTE_PATH_TO_DIRECTORY/mcp-browser-agent/dist/index.js",
      "--browser",
      "chrome"
    ]
    }
  }
}

Важно : замените ABSOLUTE_PATH_TO_DIRECTORY на полный абсолютный путь , по которому вы установили MCP.

Пример для macOS/Linux: /Users/username/mcp-browser-agent
Пример для Windows: C:\\Users\\username\\mcp-browser-agent

Если у вас уже настроены другие MCP, просто добавьте раздел "browserAgent" внутри объекта "mcpServers". Вот пример конфигурации с несколькими MCP:

{
  "mcpServers": {
    "otherMcp1": {
      "command": "...",
      "args": ["..."]
    },
    "otherMcp2": {
      "command": "...",
      "args": ["..."]
    },
    "browserAgent": {
      "command": "node",
      "args": [
        "ABSOLUTE_PATH_TO_DIRECTORY/mcp-browser-agent/dist/index.js",
      "--browser",
      "chrome"
    ]
    }
  }
}

Выбор браузера

MCP Browser Agent поддерживает несколько типов браузеров. По умолчанию он использует Chrome, но вы можете указать другой браузер несколькими способами:

Вариант 1: Файл конфигурации

Создайте или отредактируйте файл .mcp_browser_agent_config.json в вашем домашнем каталоге:

{
  "browserType": "chrome"
}

Поддерживаемые значения для browserType :

chrome — использует установленный Chrome (по умолчанию)
firefox - использует браузер Firefox «Nightly»
webkit — использует движок WebKit (Примечание: это не сам Safari, а движок рендеринга WebKit, на котором работает Safari)
edge — использует Microsoft Edge

Примечание о Safari : Playwright не обеспечивает прямую поддержку браузера Safari. Вместо этого он использует WebKit, который является движком браузера, на котором работает Safari. Реализация WebKit в Playwright обеспечивает схожую функциональность, но не идентична опыту браузера Safari.

Вариант 2: Аргумент командной строки

При ручном запуске сервера MCP можно указать тип браузера:

node dist/index.js --browser firefox

Вариант 3: Переменная среды

Установите переменную среды MCP_BROWSER_TYPE :

MCP_BROWSER_TYPE=firefox node dist/index.js

Вариант 4: Конфигурация рабочего стола Claude

При настройке MCP в claude_desktop_config.json Claude Desktop можно указать тип браузера:

{
  "mcpServers": {
    "browserAgent": {
      "command": "node",
      "args": [
        "ABSOLUTE_PATH_TO_DIRECTORY/mcp-browser-agent/dist/index.js",
        "--browser",
        "chrome"
      ]
    }
  }
}

Техническая реализация

MCP Browser Agent построен на Model Context Protocol, что позволяет Claude взаимодействовать с headful браузером через Playwright. Реализация состоит из четырех основных компонентов:

Сервер (index.ts)
- Инициализирует сервер MCP с использованием стандартного протокола Model Context Protocol
- Настраивает возможности сервера для инструментов и ресурсов
- Устанавливает связь с Клодом через stdio-транспорт
Реестр инструментов (tools.ts)
- Определяет схемы браузера и инструментов API
- Указывает параметры, правила проверки и описания
- Регистрирует инструменты на сервере MCP для обнаружения Клодом
Обработчики запросов (handlers.ts)
- Управляет запросами протокола MCP на инструменты и ресурсы
- Предоставляет журналы браузера и снимки экрана в качестве запрашиваемых ресурсов
- Направляет запросы на выполнение инструмента соответствующим обработчикам
Исполнитель (executor.ts)
- Управляет жизненным циклом браузера и API-клиента
- Реализует функции автоматизации браузера с помощью Playwright
- Обрабатывает запросы API с правильной обработкой ошибок и анализом ответов.
- Поддерживает сеанс браузера с сохранением состояния между командами

Возможности агента

В отличие от базовых интеграций, MCP Browser Agent функционирует как настоящий агент ИИ:

Поддержание постоянного состояния браузера при выполнении нескольких команд
Сбор подробных журналов консоли для отладки
Хранение снимков экрана для справки и просмотра
Управление сложными последовательностями взаимодействия
Предоставление подробной информации об ошибке для восстановления
Поддержка цепочек операций для сложных рабочих процессов

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

Инструменты браузера

Название инструмента	Описание	Параметры
`browser_navigate`	Перейдите по URL-адресу	`url` (обязательно), `timeout` , `waitUntil`
`browser_screenshot`	Сделать снимок экрана	`name` (обязательно), `selector` , `fullPage` , `mask` , `savePath`
`browser_click`	Щелкните элемент	`selector` (обязательно)
`browser_fill`	Заполните форму ввода	`selector` (обязательно), `value` (обязательно)
`browser_select`	Выберите раскрывающийся список	`selector` (обязательно), `value` (обязательно)
`browser_hover`	Наведите курсор на элемент	`selector` (обязательно)
`browser_evaluate`	Выполнить JavaScript	`script` (обязательно)

API-инструменты

Название инструмента	Описание	Параметры
`api_get`	ПОЛУЧИТЬ запрос	`url` (обязательно), `headers`
`api_post`	POST-запрос	`url` (обязательно), `data` (обязательно), `headers`
`api_put`	Запрос PUT	`url` (обязательно), `data` (обязательно), `headers`
`api_patch`	Запрос на исправление	`url` (обязательно), `data` (обязательно), `headers`
`api_delete`	УДАЛЕНИЕ запроса	`url` (обязательно), `headers`

Доступ к ресурсам

Агент браузера MCP предоставляет следующие ресурсы:

browser://logs — доступ к журналам консоли браузера
screenshot://[name] — доступ к снимкам экрана по имени

Пример использования

Вот несколько реалистичных примеров использования MCP Browser Agent с Клодом:

Базовая навигация в браузере

Navigate to the Google homepage at https://www.google.com

Take a screenshot of the current page and name it "google-homepage"

Type "weather forecast" in the search box

Простые взаимодействия

Navigate to https://www.wikipedia.org and search for "Model Context Protocol"

Go to https://the-internet.herokuapp.com/dropdown and select the option "Option 1" from the dropdown

Заполнение базовой формы

Navigate to https://the-internet.herokuapp.com/login and fill in the username field with "tomsmith" and the password field with "SuperSecretPassword!"

Go to https://the-internet.herokuapp.com/login, fill in the username and password fields, then click the login button

Простое выполнение JavaScript

Go to https://example.com and execute a JavaScript script to return the page title

Navigate to https://www.google.com and execute a JavaScript script to count the number of links on the page

Базовые запросы API

Perform a GET request to https://jsonplaceholder.typicode.com/todos/1

Make a POST request to https://jsonplaceholder.typicode.com/posts with appropriate JSON data

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

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

Ошибка «Сервер отключен»

Если вы видите ошибку «MCP Browser Agent: Server disconnected» в Claude Desktop:

Убедитесь, что сервер работает :
- Откройте терминал и вручную запустите node dist/index.js из каталога проекта.
- Если сервер запустится успешно, используйте Claude, оставив этот терминал открытым.
Проверьте вашу конфигурацию :
- Убедитесь, что абсолютный путь в claude_desktop_config.json правильный для вашей системы.
- Дважды проверьте, что вы использовали двойные обратные косые черты ( \\ ) для путей Windows.
- Убедитесь, что вы используете полный путь от корня вашей файловой системы.

Браузер не отображается

Если браузер не запускается или вы его не видите:

Проверьте, установлен ли указанный браузер.
- Убедитесь, что в вашей системе установлен браузер (Chrome, Firefox, Edge или Safari/WebKit)
- Драйверы браузера обрабатываются Playwright автоматически.
Перезагрузите сервер и Claude Desktop.
- Завершите все существующие процессы узлов, которые могут запускать сервер.
- Перезапустите Claude Desktop, чтобы установить новое соединение.

Процесс браузера не закрывается должным образом

Известны проблемы с браузерами Chromium и Chrome, когда процесс иногда не завершается должным образом после использования. Если у вас возникла эта проблема:

Закройте процесс браузера вручную :
- Windows : нажмите Ctrl+Shift+Esc, чтобы открыть диспетчер задач, найдите процесс Chrome/Chromium и завершите его.
- macOS : Откройте «Мониторинг системы» (Приложения > Утилиты > Мониторинг системы), найдите процесс Chrome/Chromium и нажмите X, чтобы завершить его.
- Linux : выполните команду ps aux | grep chrome или ps aux | grep chromium чтобы найти процесс, затем kill <PID> , чтобы завершить его.
Примечание о совместимости браузеров :
- Эта проблема наблюдалась в основном с Chromium и Chrome.
- Встроенные браузеры Firefox и Playwright обычно не сталкиваются с этой проблемой.

[!ВНИМАНИЕ] Эта интеграция MCP построена на Playwright, который имеет известные проблемы и ошибки, которые могут повлиять на его работу. Пожалуйста, сообщайте о любых проблемах, с которыми вы сталкиваетесь при автоматизации браузера, в Playwright's GitHub issues . Команда Playwright постоянно работает над решением этих проблем, но этот агент обеспечивает основу для возможностей автоматизации браузера с Claude Desktop, несмотря на эти ограничения.

Разработка

Структура проекта

src/index.ts : Основная точка входа и инициализация сервера MCP
src/tools.ts : Схемы инструментов и регистрация
src/handlers.ts : Обработчики запросов MCP для инструментов и ресурсов
src/executor.ts : Логика реализации инструмента с использованием Playwright

Здание

npm run build

Наблюдение за изменениями

npm run watch

Тестирование

Проект включает в себя тесты для проверки основных функций и работы браузера.

npm test               # Run tests
npm run test:watch     # Watch mode
npm run test:coverage  # Coverage report

Тесты проверяют целостность конфигурации, функции автоматизации браузера, обработку ошибок и очистку процесса. Тестовый набор в частности фокусируется на обеспечении надлежащей обработки процессов браузера из-за известных проблем с завершением работы Chrome/Chromium.

Соображения безопасности

[!ВНИМАНИЕ] Эта интеграция MCP обеспечивает Claude возможностями автономного управления браузером. Пожалуйста, ознакомьтесь с нашей Политикой безопасности для получения важной информации о запрещенных видах использования, последствиях для безопасности и передовых методах.

MCP Browser Agent разработан для законных задач автоматизации, но потенциально может быть использован не по назначению. Пользователи несут ответственность за обеспечение соответствия своего использования всем применимым законам, условиям обслуживания и этическим нормам. Для получения дополнительной информации см. нашу подробную Политику безопасности .

Внося вклад

Приветствуются вклады в MCP Browser Agent! Вот некоторые области, где вы можете помочь:

Добавление новых возможностей автоматизации браузера
Улучшение обработки ошибок и восстановления
Улучшение управления скриншотами и ресурсами
Создание полезных рабочих процессов и примеров
Оптимизация производительности для сложных операций

Лицензия

Данный проект лицензирован в соответствии с Mozilla Public License 2.0 — подробности см. в файле LICENSE .

Integrations