Crawl-MCP: Неофициальный MCP-сервер для crawl4ai

⚠️ Важно: Это неофициальная реализация MCP-сервера для отличной библиотеки crawl4ai. Не связана с оригинальным проектом crawl4ai.

Полнофункциональный сервер протокола контекста модели (MCP), который объединяет мощную библиотеку crawl4ai с передовыми возможностями ИИ. Извлекайте и анализируйте контент из любого источника: веб-страниц, PDF-файлов, документов Office, видео YouTube и многого другого. Включает интеллектуальное суммирование для значительного сокращения использования токенов при сохранении важной информации.

🌟 Ключевые особенности

• 🔍 Интеграция с поиском Google - 7 оптимизированных жанров поиска с официальными операторами Google

• 🔍 Продвинутый веб-краулинг: поддержка JavaScript, глубокое картирование сайтов, извлечение сущностей

• 🌐 Универсальное извлечение контента: веб-страницы, PDF, документы Word, Excel, PowerPoint, ZIP-архивы

• 🤖 ИИ-суммирование: умное сокращение токенов (до 88,5%) при сохранении основной информации

• 🎬 Интеграция с YouTube: извлечение транскриптов видео и их краткое содержание без API-ключей

• ⚡ Готовность к продакшену: 19 специализированных инструментов с комплексной обработкой ошибок

Related MCP server: Crawl4AI MCP Server

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

Предварительные требования (обязательно)

• Python 3.11 или выше (FastMCP требует Python 3.11+)

Установка системных зависимостей для Playwright:

Ubuntu 24.04 LTS (требуется ручная настройка):

# Manual setup required due to t64 library transition
sudo apt update && sudo apt install -y \
  libnss3 libatk-bridge2.0-0 libxss1 libasound2t64 \
  libgbm1 libgtk-3-0t64 libxshmfence-dev libxrandr2 \
  libxcomposite1 libxcursor1 libxdamage1 libxi6 \
  fonts-noto-color-emoji fonts-unifont python3-venv python3-pip

python3 -m venv venv && source venv/bin/activate
pip install playwright==1.55.0 && playwright install chromium
sudo playwright install-deps

Другие Linux/macOS:

sudo bash scripts/prepare_for_uvx_playwright.sh

Windows (от имени администратора):

scripts/prepare_for_uvx_playwright.ps1

Установка

UVX (рекомендуется — проще всего):

# After system preparation above - that's it!
uvx --from git+https://github.com/walksoda/crawl-mcp crawl-mcp

Docker (готов к продакшену):

# Clone the repository
git clone https://github.com/walksoda/crawl-mcp
cd crawl-mcp

# Build and run with Docker Compose (STDIO mode)
docker-compose up --build

# Or build and run HTTP mode on port 8000
docker-compose --profile http up --build crawl4ai-mcp-http

# Or build manually
docker build -t crawl4ai-mcp .
docker run -it crawl4ai-mcp

Возможности Docker:

• 🔧 Поддержка нескольких браузеров: Chromium, Firefox, Webkit (headless)

• 🐧 Google Chrome: Дополнительный Chrome Stable для совместимости

• ⚡ Оптимизированная производительность: Предварительно настроенные флаги браузера для Docker

• 🔒 Безопасность: Запуск от пользователя без прав root

• 📦 Полный набор зависимостей: Все необходимые библиотеки включены

Настройка Claude Desktop

Установка через UVX: Добавьте в ваш claude_desktop_config.json:

{
  "mcpServers": {
    "crawl-mcp": {
      "transport": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/walksoda/crawl-mcp",
        "crawl-mcp"
      ],
      "env": {
        "CRAWL4AI_LANG": "en"
      }
    }
  }
}

Режим Docker HTTP:

{
  "mcpServers": {
    "crawl-mcp": {
      "transport": "http",
      "baseUrl": "http://localhost:8000"
    }
  }
}

Для японского интерфейса:

"env": {
  "CRAWL4AI_LANG": "ja"
}

📖 Документация

Документация по языкам

• English: директория docs/

• 日本語: директория docs/ja/

🛠️ Обзор инструментов

Веб-краулинг (3)

• crawl_url - Извлечение контента веб-страницы с поддержкой JavaScript

• deep_crawl_site - Краулинг нескольких страниц сайта с настраиваемой глубиной

• crawl_url_with_fallback - Краулинг со стратегиями резервного копирования для сайтов с защитой от ботов

Извлечение данных (3)

• intelligent_extract - Извлечение специфических данных с веб-страниц с помощью LLM

• extract_entities - Извлечение сущностей (email, телефоны и т.д.) с веб-страниц

• extract_structured_data - Извлечение структурированных данных с помощью CSS-селекторов или LLM

YouTube (4)

• extract_youtube_transcript - Извлечение транскриптов YouTube с временными метками

• batch_extract_youtube_transcripts - Извлечение транскриптов из нескольких видео YouTube (макс. 3)

• get_youtube_video_info - Получение метаданных видео YouTube и доступности транскрипта

• extract_youtube_comments - Извлечение комментариев к видео YouTube с пагинацией

Поиск (4)

• search_google - Поиск в Google с фильтрацией по жанрам

• batch_search_google - Выполнение нескольких поисковых запросов в Google (макс. 3)

• search_and_crawl - Поиск в Google и краулинг топовых результатов

• get_search_genres - Получение доступных жанров поиска

Обработка файлов (3)

• process_file - Конвертация PDF, Word, Excel, PowerPoint, ZIP в markdown

• get_supported_file_formats - Получение списка поддерживаемых форматов файлов и возможностей

• enhanced_process_large_content - Обработка большого контента с чанкингом и фильтрацией BM25

Пакетные операции (2)

• batch_crawl - Краулинг нескольких URL с резервными стратегиями (макс. 3 URL)

• multi_url_crawl - Краулинг нескольких URL с конфигурацией на основе шаблонов (макс. 5 шаблонов URL)

💾 Сохранение больших результатов на диск (экономия токенов)

Все инструменты сбора информации принимают необязательный параметр output_path, который записывает полностью полученный контент прямо на диск и возвращает компактный ответ, содержащий только метаданные. Это позволяет LLM получать огромные страницы, длинные транскрипты YouTube или целые пакеты данных, не превышая лимит контекста — читайте из сохраненного файла только тогда, когда это необходимо.

Как это работает:

• Инструменты для одного файла (например, crawl_url, extract_youtube_transcript) записывают один .md (или .json для инструментов типа JSON) — передайте абсолютный путь к файлу; расширение добавляется автоматически, если оно опущено. Существующий обычный файл по этому пути будет отклонен, если не указано overwrite=true.

• Пакетные инструменты (batch_crawl, multi_url_crawl, deep_crawl_site, search_and_crawl, batch_extract_youtube_transcripts) ожидают абсолютный путь к директории и записывают один .md на каждый URL плюс index.json. Любой несуществующий путь рассматривается как директория и создается — включая имена, содержащие точки, такие как /tmp/run.v1. Если путь уже существует как обычный файл, вызов будет отклонен. batch_crawl / multi_url_crawl сохраняют свою форму возврата list и встраивают ключ output_file в каждый успешный элемент.

• Инструменты с словарем запросов (search_google, batch_search_google, search_and_crawl, batch_extract_youtube_transcripts) считывают ключи сохранения напрямую из своего словаря запросов.

• Общие параметры: output_path (абсолютный; None или "" пропускает сохранение), include_content_in_response (по умолчанию false — если true, контент также включается в ответ, все еще подвергается любому нарезанию content_limit/content_offset/max_content_per_page), overwrite (по умолчанию false).

• Запись атомарна для каждого файла (временный файл + os.replace); родительские директории создаются автоматически; полная неразрезанная полезная нагрузка сохраняется до любого нарезания или внутренней обрезки инструмента, поэтому копия на диске всегда полная, даже если ответ был обрезан.

• Пакетные инструменты со словарем (deep_crawl_site, search_and_crawl, batch_extract_youtube_transcripts) пропускают сохранение для элементов, которые сообщают success=false; они все равно появляются в index.json с file: null, чтобы вызывающие стороны могли проанализировать список попыток.

Пример для одного Markdown-файла:

{
  "tool": "crawl_url",
  "arguments": {
    "url": "https://example.com/long-article",
    "output_path": "/tmp/crawl_out/article.md"
  }
}

Структурированное извлечение JSON (расширение добавляется автоматически):

{
  "tool": "extract_structured_data",
  "arguments": {
    "url": "https://example.com/products",
    "extraction_type": "css",
    "css_selectors": {"price": ".price", "name": "h1"},
    "output_path": "/tmp/crawl_out/products"
  }
}

Режим пакетной директории:

{
  "tool": "batch_crawl",
  "arguments": {
    "urls": ["https://a.example", "https://b.example"],
    "output_path": "/tmp/crawl_out/batch_run1"
  }
}

Каждый сохраненный markdown-файл начинается с блока YAML frontmatter, содержащего url, title, fetched_at и source_tool, поэтому артефакт является самоописываемым.

🎯 Типичные сценарии использования

Исследование контента:

search_and_crawl → extract_structured_data → analysis

Анализ документации:

deep_crawl_site → batch processing → extraction

Анализ медиа:

extract_youtube_transcript → summarization workflow

Картирование сайтов:

batch_crawl → multi_url_crawl → comprehensive data

🚨 Быстрое устранение неполадок

Проблемы с установкой:

1. Перезапустите скрипты установки с соответствующими привилегиями

2. Попробуйте метод установки для разработки

3. Проверьте, установлены ли зависимости браузера

Проблемы с производительностью:

• Используйте wait_for_js: true для сайтов с интенсивным использованием JavaScript

• Увеличьте время ожидания (timeout) для медленно загружающихся страниц

• Используйте extract_structured_data для целевого извлечения

Проблемы с конфигурацией:

• Проверьте синтаксис JSON в claude_desktop_config.json

• Убедитесь, что пути к файлам абсолютные

• Перезапустите Claude Desktop после внесения изменений в конфигурацию

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

• Оригинальная библиотека: crawl4ai от unclecode

• MCP-обертка: Этот репозиторий (walksoda)

• Реализация: Неофициальная сторонняя интеграция

📄 Лицензия

Этот проект является неофициальной оберткой вокруг библиотеки crawl4ai. Пожалуйста, обратитесь к оригинальной лицензии crawl4ai для получения информации о базовой функциональности.

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

Смотрите наше Руководство по разработке для получения рекомендаций по внесению вклада и инструкций по настройке среды разработки.

🔗 Связанные проекты

• crawl4ai - Базовая библиотека для веб-краулинга

• Model Context Protocol - Стандарт, который реализует этот сервер

• Claude Desktop - Основной клиент для MCP-серверов