Browser MCP Server

Сервер MCP (Model Context Protocol), который даёт ИИ-агентам настоящий, устойчивый к антибот-блокировкам браузер через Zyte API — открывайте страницы, выполняйте клики/ввод текста/прокрутку, делайте скриншоты и извлекайте структурированные данные, с автоматической ротацией прокси/IP и предотвращением блокировок.

Написан на NestJS и @nestjs-mcp/server, напрямую обращается к эндпоинту /extract сервиса Zyte по HTTP. Транспорт — только streamable HTTP; сервер работает без сохранения состояния (stateless) и доступен на единственном эндпоинте /mcp.

Настройка

1. Скопируйте .env.example в .env и заполните его:

   Variable	Required	Description
   ZYTE_API_KEY	Да	Ваш ключ Zyte API
   ZYTE_API_BASE_URL	Нет	Переопределяет базовый URL Zyte API (по умолчанию https://api.zyte.com/v1)
   PORT	Нет	HTTP-порт (по умолчанию 3000)
   BROWSER_TIMEOUT_MS	Нет	Таймаут запроса при вызове Zyte (по умолчанию 30000)
   BROWSER_MAX_RETRIES	Нет	Повторы с экспоненциальной задержкой для ответов rate-limit (429/503) и временной блокировки (520) (по умолчанию 2)

2. Установите зависимости и запустите сервер:

   pnpm install
   pnpm run start:dev

   Эндпоинт MCP доступен по адресу http://localhost:3000/mcp.

Related MCP server: Stealth Browser MCP

Инструменты

browser_browse, browser_screenshot и browser_extract принимают необязательный параметр sessionId (возвращённый предыдущим вызовом), чтобы переиспользовать один и тот же IP-адрес и cookie-хранилище между несколькими вызовами инструментов — это удобно для сохранения входа в систему или постоянного IP при выполнении многошаговой задачи. Обратите внимание: согласно документации Zyte о сессиях, это не сохраняет фактическое состояние браузера/вкладки (введённые данные в форме, позиция прокрутки, открытые модальные окна и т.п.) между вызовами — каждый вызов загружает новую страницу, используя ту же сетевую идентичность и cookies.

actions — это последовательность шагов, выполняемых до получения результата: click, type, select, hover, keyPress, scrollBottom, scrollTo, waitForSelector, waitForTimeout, waitForNavigation, goto, evaluate. Действия, нацеленные на элемент, принимают selector: { type: "css" | "xpath", value: string }.

browser_search обращается к отдельному эндпоинту Zyte /v1/search (не /v1/extract) и принимает domain (поддерживаемая поисковая система, например "google.com"), query и необязательные параметры maxResults (10-100), geolocation и locale.

Ответы Zyte с ограничением частоты (429/503) и временной блокировкой (520) автоматически повторяются с экспоненциальной задержкой до BROWSER_MAX_RETRIES раз, согласно руководству Zyte по обработке ошибок. Прочие ошибочные ответы (некорректный запрос, постоянная блокировка, приостановленный аккаунт) отображаются сразу, а type ошибки Zyte включается в сообщение, если это возможно.

Подключение клиента

Пример конфигурации удалённого MCP-клиента (например, Claude Desktop / Claude Code), указывающего на запущенный экземпляр:

{
  "mcpServers": {
    "browser": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

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

pnpm test        # unit tests (service + resolver, global fetch mocked)
pnpm run lint    # eslint
pnpm run build   # type-check + compile

Модульные тесты подменяют глобальный fetch, используемый для вызова Zyte. Чтобы проверить работу end-to-end с реальным API, запустите сервер с настоящим ZYTE_API_KEY и используйте pnpm dlx @modelcontextprotocol/inspector http://localhost:3000/mcp или curl, чтобы выполнить initialize → tools/list → tools/call.