Crawl-MCP: Servidor MCP no oficial para crawl4ai

⚠️ Importante: Esta es una implementación de servidor MCP no oficial para la excelente biblioteca crawl4ai. No está afiliado con el proyecto original crawl4ai.

Un servidor completo del Protocolo de Contexto de Modelo (MCP) que envuelve la potente biblioteca crawl4ai con capacidades avanzadas de IA. Extrae y analiza contenido de cualquier fuente: páginas web, archivos PDF, documentos de Office, vídeos de YouTube y más. Incluye resumen inteligente para reducir drásticamente el uso de tokens mientras se conserva la información esencial.

🌟 Características principales

• 🔍 Integración con la búsqueda de Google - 7 géneros de búsqueda optimizados con operadores oficiales de Google

• 🔍 Rastreo web avanzado: soporte para JavaScript, mapeo profundo de sitios, extracción de entidades

• 🌐 Extracción universal de contenido: páginas web, archivos PDF, documentos de Word, Excel, PowerPoint, archivos ZIP

• 🤖 Resumen potenciado por IA: reducción inteligente de tokens (hasta un 88,5%) mientras se conserva la información esencial

• 🎬 Integración con YouTube: extrae transcripciones y resúmenes de vídeos sin necesidad de claves API

• ⚡ Listo para producción: 19 herramientas especializadas con gestión integral de errores

Related MCP server: Crawl4AI MCP Server

🚀 Inicio rápido

Requisitos previos (necesarios primero)

• Python 3.11 o superior (FastMCP requiere Python 3.11+)

Instalar dependencias del sistema para Playwright:

Ubuntu 24.04 LTS (requiere manual):

# 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

Otros Linux/macOS:

sudo bash scripts/prepare_for_uvx_playwright.sh

Windows (como administrador):

scripts/prepare_for_uvx_playwright.ps1

Instalación

UVX (Recomendado - El más sencillo):

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

Docker (Listo para producción):

# 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

Características de Docker:

• 🔧 Soporte para múltiples navegadores: navegadores Chromium, Firefox y Webkit en modo headless

• 🐧 Google Chrome: Chrome Stable adicional para compatibilidad

• ⚡ Rendimiento optimizado: flags de navegador preconfiguradas para Docker

• 🔒 Seguridad: ejecución con usuario no root

• 📦 Dependencias completas: todas las bibliotecas necesarias incluidas

Configuración de Claude Desktop

Instalación con UVX: Agregue esto a su 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"
      }
    }
  }
}

Modo HTTP de Docker:

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

Para interfaz en japonés:

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

📖 Documentación

Documentación específica por idioma

• Inglés: directorio docs/

• 日本語: directorio docs/ja/

🛠️ Resumen de herramientas

Rastreo web (3)

• crawl_url - Extrae contenido de páginas web con soporte para JavaScript

• deep_crawl_site - Rastrea múltiples páginas de un sitio con profundidad configurable

• crawl_url_with_fallback - Rastrea con estrategias de respaldo para sitios anti-bot

Extracción de datos (3)

• intelligent_extract - Extrae datos específicos de páginas web usando LLM

• extract_entities - Extrae entidades (correos electrónicos, teléfonos, etc.) de páginas web

• extract_structured_data - Extrae datos estructurados usando selectores CSS o LLM

YouTube (4)

• extract_youtube_transcript - Extrae transcripciones de YouTube con marcas de tiempo

• batch_extract_youtube_transcripts - Extrae transcripciones de múltiples vídeos de YouTube (máx. 3)

• get_youtube_video_info - Obtiene metadatos de vídeos de YouTube y disponibilidad de transcripciones

• extract_youtube_comments - Extrae comentarios de vídeos de YouTube con paginación

Búsqueda (4)

• search_google - Busca en Google con filtrado de género

• batch_search_google - Realiza múltiples búsquedas en Google (máx. 3)

• search_and_crawl - Busca en Google y rastrea los mejores resultados

• get_search_genres - Obtiene los géneros de búsqueda disponibles

Procesamiento de archivos (3)

• process_file - Convierte PDF, Word, Excel, PowerPoint, ZIP a markdown

• get_supported_file_formats - Obtiene los formatos de archivo y capacidades compatibles

• enhanced_process_large_content - Procesa contenido grande con fragmentación y filtrado BM25

Operaciones por lotes (2)

• batch_crawl - Rastrea múltiples URLs con respaldo (máx. 3 URLs)

• multi_url_crawl - Rastreo de múltiples URLs con configuración basada en patrones (máx. 5 patrones de URL)

💾 Persistir resultados grandes en disco (ahorrador de tokens)

Todas las herramientas de recopilación de información aceptan un parámetro opcional output_path que escribe el contenido completo obtenido directamente en el disco y devuelve una respuesta ligera solo con metadatos. Esto permite que un LLM obtenga páginas enormes, transcripciones largas de YouTube o lotes completos sin agotar su presupuesto de contexto; lea desde el archivo guardado solo cuando sea necesario.

Cómo funciona:

• Las herramientas de un solo archivo (p. ej., crawl_url, extract_youtube_transcript) escriben un .md (o .json para herramientas de tipo JSON); pase una ruta de archivo absoluta; la extensión se añade automáticamente si se omite. Se rechaza un archivo normal existente en esa ruta a menos que overwrite=true.

• Las herramientas por lotes (batch_crawl, multi_url_crawl, deep_crawl_site, search_and_crawl, batch_extract_youtube_transcripts) esperan una ruta de directorio absoluta y escriben un .md por URL más un index.json. Cualquier ruta inexistente se trata como un directorio y se crea, incluidos los nombres que contienen puntos como /tmp/run.v1. Si la ruta ya existe como un archivo normal, la llamada se rechaza. batch_crawl / multi_url_crawl mantienen su forma de retorno de list e incrustan una clave output_file en cada elemento exitoso.

• Las herramientas de diccionario de solicitud (search_google, batch_search_google, search_and_crawl, batch_extract_youtube_transcripts) leen las claves de persistencia directamente de su diccionario de solicitud.

• Parámetros comunes: output_path (absoluto; None o "" omite la persistencia), include_content_in_response (predeterminado false; cuando es true, el contenido también se incluye en la respuesta, todavía sujeto a cualquier recorte de content_limit/content_offset/max_content_per_page), overwrite (predeterminado false).

• Las escrituras son atómicas por archivo (archivo temporal + os.replace); los directorios principales se crean automáticamente; la carga útil completa sin recortar se persiste antes de cualquier recorte o truncamiento interno de la herramienta, por lo que la copia en disco siempre está completa incluso cuando la respuesta está recortada.

• Las herramientas de diccionario por lotes (deep_crawl_site, search_and_crawl, batch_extract_youtube_transcripts) omiten la persistencia por elemento para aquellos que informan success=false; estos aún aparecen en index.json con file: null para que los llamadores puedan razonar sobre la lista de intentos.

Ejemplo de archivo único Markdown:

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

Extracción estructurada JSON (extensión añadida automáticamente):

{
  "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"
  }
}

Modo de directorio por lotes:

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

Cada archivo markdown persistido comienza con un bloque YAML frontmatter que contiene url, title, fetched_at y source_tool para que el artefacto sea autodescriptivo.

🎯 Casos de uso comunes

Investigación de contenido:

search_and_crawl → extract_structured_data → analysis

Minería de documentación:

deep_crawl_site → batch processing → extraction

Análisis de medios:

extract_youtube_transcript → summarization workflow

Mapeo de sitios:

batch_crawl → multi_url_crawl → comprehensive data

🚨 Solución de problemas rápida

Problemas de instalación:

1. Vuelva a ejecutar los scripts de configuración con los privilegios adecuados

2. Pruebe el método de instalación de desarrollo

3. Compruebe que las dependencias del navegador estén instaladas

Problemas de rendimiento:

• Use wait_for_js: true para sitios con mucho JavaScript

• Aumente el tiempo de espera para páginas de carga lenta

• Use extract_structured_data para una extracción dirigida

Problemas de configuración:

• Compruebe la sintaxis JSON en claude_desktop_config.json

• Verifique que las rutas de archivo sean absolutas

• Reinicie Claude Desktop después de los cambios de configuración

🏗️ Estructura del proyecto

• Biblioteca original: crawl4ai por unclecode

• Envoltorio MCP: Este repositorio (walksoda)

• Implementación: Integración de terceros no oficial

📄 Licencia

Este proyecto es un envoltorio no oficial de la biblioteca crawl4ai. Consulte la licencia original de crawl4ai para conocer la funcionalidad subyacente.

🤝 Contribución

Consulte nuestra Guía de desarrollo para conocer las pautas de contribución y las instrucciones de configuración de desarrollo.

🔗 Proyectos relacionados

• crawl4ai - La biblioteca de rastreo web subyacente

• Model Context Protocol - El estándar que implementa este servidor

• Claude Desktop - Cliente principal para servidores MCP