Сервис Web Scrapper (MCP Stdin/Stdout и HTTP)

MCP-сервер на Python для надежного headless веб-скрейпинга — извлекает основной текстовый контент с веб-страниц и выводит его в формате Markdown, текста или HTML для бесшовной интеграции с ИИ и системами автоматизации.

Основные возможности

• Headless-скрейпинг в браузере (Playwright, BeautifulSoup, Markdownify)

• Вывод в форматах Markdown, текст или HTML

• Разработан для интеграции с MCP (Model Context Protocol) через stdio/JSON-RPC

• Двойной транспорт: stdio (по умолчанию) и Streamable HTTP для режима общего сервиса

• Постоянный пул браузеров: Chromium остается активным между запросами для быстрого скрейпинга

• Умное ожидание DOM: стабилизация контента на основе MutationObserver вместо фиксированных пауз

• Контейнеризация Docker с готовыми образами

• Настройка через переменные окружения

• Надежная обработка ошибок (тайм-ауты, HTTP-ошибки, Cloudflare и т. д.)

• Ограничение частоты запросов (rate limiting) для каждого домена

• Простая интеграция с ИИ-инструментами и IDE (Cursor, Claude Desktop, Continue, JetBrains, Zed и др.)

• Установка в один клик для Cursor, интерактивный установщик для Claude

Related MCP server: Fetcher MCP

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

Запуск через Docker (режим stdio — один контейнер на клиента)

docker run -i --rm ghcr.io/justazul/web-scrapper-stdio

Запуск в качестве общего HTTP-сервиса (один контейнер, несколько клиентов)

docker run -d --name web-scraper \
  -e MCP_TRANSPORT=streamable-http \
  -e MCP_HTTP_PORT=8080 \
  -e BROWSER_POOL_SIZE=3 \
  -p 8080:8080 \
  --shm-size=3gb \
  ghcr.io/justazul/web-scrapper-stdio

Или с помощью Docker Compose:

docker compose --profile service up -d

Установка в один клик (Cursor IDE)

Режимы транспорта

stdio (по умолчанию)

Каждый MCP-клиент запускает собственный контейнер через docker run -i. Просто, не требует настройки, работает с любым MCP-клиентом.

{
  "mcpServers": {
    "web-scrapper-stdio": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/justazul/web-scrapper-stdio"]
    }
  }
}

Streamable HTTP (общий сервис)

Запустите один постоянный контейнер, который обслуживает несколько MCP-клиентов по HTTP. Экономит ресурсы при запуске нескольких экземпляров ИИ-инструментов (например, нескольких сессий Claude Code).

Запуск сервиса:

docker run -d --name web-scraper \
  -e MCP_TRANSPORT=streamable-http \
  -e MCP_HTTP_PORT=8080 \
  -p 8080:8080 \
  --shm-size=3gb \
  ghcr.io/justazul/web-scrapper-stdio

Подключение из вашего MCP-клиента:

{
  "mcpServers": {
    "web-scrapper": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

Интеграция с ИИ-инструментами и IDE

Этот сервис поддерживает интеграцию с широким спектром ИИ-инструментов и IDE, реализующих протокол Model Context Protocol (MCP). Ниже приведены готовые примеры конфигурации для наиболее популярных сред. При необходимости замените образ/тег для пользовательских сборок.

Cursor IDE

Добавьте в ваш .cursor/mcp.json (на уровне проекта) или ~/.cursor/mcp.json (глобально):

{
  "mcpServers": {
    "web-scrapper-stdio": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/justazul/web-scrapper-stdio"
      ]
    }
  }
}

Claude Desktop

Добавьте в конфигурацию MCP для Claude Desktop (обычно claude_desktop_config.json):

{
  "mcpServers": {
    "web-scrapper-stdio": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/justazul/web-scrapper-stdio"
      ]
    }
  }
}

Claude Code

Добавьте в ваш .mcp.json или глобальный ~/.claude.json:

Режим stdio (один контейнер на сессию):

{
  "mcpServers": {
    "web-scrapper-stdio": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/justazul/web-scrapper-stdio"]
    }
  }
}

Режим HTTP (общий сервис — сначала запустите сервис):

{
  "mcpServers": {
    "web-scrapper": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

Continue (плагин для VSCode/JetBrains)

Добавьте в ваш continue.config.json или через настройки MCP в плагине Continue:

{
  "mcpServers": {
    "web-scrapper-stdio": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/justazul/web-scrapper-stdio"
      ]
    }
  }
}

IntelliJ IDEA (JetBrains AI Assistant)

Перейдите в Settings > Tools > AI Assistant > Model Context Protocol (MCP) и добавьте новый сервер. Используйте:

{
  "command": "docker",
  "args": [
    "run",
    "-i",
    "--rm",
    "ghcr.io/justazul/web-scrapper-stdio"
  ]
}

Zed Editor

Добавьте в вашу конфигурацию MCP для Zed (см. документацию Zed для точного пути):

{
  "mcpServers": {
    "web-scrapper-stdio": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/justazul/web-scrapper-stdio"
      ]
    }
  }
}

Использование

MCP-сервер (Инструмент/Промпт)

Этот веб-скрейпер используется как инструмент MCP (Model Context Protocol), что позволяет напрямую использовать его ИИ-моделям или другим системам автоматизации.

Инструмент: scrape_web

Параметры:

• url (строка, обязательно): URL для скрейпинга

• max_length (целое число, опционально): Максимальная длина возвращаемого контента (по умолчанию: без ограничений)

• timeout_seconds (целое число, опционально): Тайм-аут загрузки страницы в секундах (по умолчанию: 30)

• user_agent (строка, опционально): Пользовательская строка User-Agent, передаваемая напрямую в браузер (по умолчанию выбирается случайный)

• wait_for_network_idle (логическое значение, опционально): Ожидать завершения сетевой активности перед скрейпингом (по умолчанию: true)

• custom_elements_to_remove (список строк, опционально): Дополнительные HTML-элементы (CSS-селекторы) для удаления перед извлечением

• grace_period_seconds (число с плавающей точкой, опционально): Время ожидания рендеринга JS после навигации. Использует MutationObserver для умного обнаружения. Установите 0, чтобы пропустить полностью. (по умолчанию: 0.5)

• output_format (строка, опционально): markdown, text или html (по умолчанию: markdown)

• click_selector (строка, опционально): Если указано, кликнуть по элементу, соответствующему этому селектору, после навигации и перед извлечением

Возвращает:

• Контент веб-страницы в формате Markdown в виде строки

• Ошибки возвращаются как строки, начинающиеся с [ERROR] ...

Пример: Использование click_selector и custom_elements_to_remove

{
  "url": "http://uitestingplayground.com/clientdelay",
  "click_selector": "#ajaxButton",
  "grace_period_seconds": 10,
  "custom_elements_to_remove": [".ads-banner", "#popup"],
  "output_format": "markdown"
}

Промпт: scrape

Параметры:

• url (строка, обязательно): URL для скрейпинга

• output_format (строка, опционально): markdown, text или html (по умолчанию: markdown)

Возвращает:

• Контент, извлеченный с веб-страницы в выбранном формате

Примечание:

• Markdown возвращается по умолчанию, но текст или HTML можно запросить через output_format.

• Скрейпер не проверяет robots.txt и попытается получить любой предоставленный URL.

• REST API или CLI-инструмент не включены; это чисто MCP stdio/JSON-RPC инструмент.

• Скрейпер всегда извлекает полное содержимое <body> веб-страниц, применяя только базовое удаление «шума» (удаление тегов script, style, nav, footer, aside, header и подобных неинформативных тегов). Скрейпер обнаруживает и обрабатывает экраны проверки Cloudflare, возвращая специфическую строку ошибки.

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

Вы можете переопределить большинство параметров конфигурации с помощью переменных окружения:

Основные настройки

• DEFAULT_TIMEOUT_SECONDS: Тайм-аут для загрузки страниц и навигации (по умолчанию: 30)

• DEFAULT_MIN_CONTENT_LENGTH: Минимальная длина контента для извлеченного текста (по умолчанию: 100)

• DEFAULT_MIN_CONTENT_LENGTH_SEARCH_APP: Минимальная длина контента для доменов search.app (по умолчанию: 30)

• DEFAULT_MIN_SECONDS_BETWEEN_REQUESTS: Минимальная задержка между запросами к одному домену (по умолчанию: 2)

• DEFAULT_GRACE_PERIOD_SECONDS: Задержка по умолчанию для рендеринга JS (по умолчанию: 0.5)

• DEBUG_LOGS_ENABLED: Установите true для включения отладочных логов (по умолчанию: false)

Пул браузеров

• BROWSER_POOL_ENABLED: Включить постоянный пул браузеров (по умолчанию: true). Установите false для запуска браузера при каждом запросе (исходное поведение).

• BROWSER_POOL_SIZE: Количество экземпляров Chromium для поддержания в активном состоянии (по умолчанию: 2). Каждый экземпляр потребляет ~100-200 МБ ОЗУ.

Транспорт

• MCP_TRANSPORT: Режим транспорта — stdio или streamable-http (по умолчанию: stdio)

• MCP_HTTP_PORT: Порт HTTP-сервера при использовании транспорта streamable-http (по умолчанию: 8080)

• MCP_HTTP_HOST: Адрес привязки HTTP-сервера (по умолчанию: 0.0.0.0)

Обход Cloudflare

• CAPTCHA_API_KEY: API-ключ для сервиса решения капчи. Если задан, задачи Cloudflare Turnstile решаются автоматически. Если пуст (по умолчанию), страницы с защитой CF возвращают ошибку.

• CAPTCHA_PROVIDER: Провайдер решения капчи — 2captcha, capsolver или capmonster (по умолчанию: 2captcha)

• CAPTCHA_BASE_URL: Пользовательский API-эндпоинт для решения (по умолчанию: использует официальный URL провайдера)

• CAPTCHA_TIMEOUT: Тайм-аут в секундах для решения капчи (по умолчанию: 120)

Настройки тестирования

• DEFAULT_TEST_REQUEST_TIMEOUT: Тайм-аут для тестовых запросов (по умолчанию: 10)

• DEFAULT_TEST_NO_DELAY_THRESHOLD: Порог для пропуска искусственных задержек в тестах (по умолчанию: 0.5)

Обработка ошибок и ограничения

• Скрейпер обнаруживает и возвращает ошибки при сбоях навигации, тайм-аутах, HTTP-ошибках (включая 404) и анти-бот проверках Cloudflare.

• Ограничение частоты запросов применяется для каждого домена (по умолчанию: 2 секунды между запросами).

• Обход Cloudflare: Использует Patchright (анти-детектирование на уровне CDP) для пассивного обхода. Большинство сайтов с защитой CF скрейпятся без вызова проверки. Когда срабатывает проверка Turnstile и задан CAPTCHA_API_KEY, она решается автоматически через сторонний API.

• Ограничения:

  • Нет REST API или CLI-инструмента (только MCP stdio/JSON-RPC)

  • Нет поддержки контента, отличного от HTML (PDF, изображения и т. д.)

  • Нет аутентификации или управления сессиями для защищенных страниц

  • Не предназначен для масштабного скрейпинга или нарушения условий использования сайтов

Разработка и тестирование

Запуск тестов (Docker Compose)

Все тесты должны запускаться с использованием Docker Compose. Не запускайте тесты вне Docker.

• Все тесты:

docker compose up --build --abort-on-container-exit test

• Только тесты MCP-сервера:

docker compose up --build --abort-on-container-exit test_mcp

• Только тесты скрейпера:

docker compose up --build --abort-on-container-exit test_scrapper

Запуск бенчмарков

docker compose run --rm benchmark

Результаты сохраняются в benchmarks/RESULTS.md.

Вклад в проект

Мы приветствуем ваш вклад! Пожалуйста, открывайте issues или pull requests для исправления ошибок, добавления функций или улучшений. Если вы планируете внести значительные изменения, сначала откройте issue для обсуждения вашего предложения.

Лицензия

Этот проект лицензирован по лицензии MIT.