Servicio de Web Scrapper (MCP Stdin/Stdout & HTTP)

Un servidor MCP basado en Python para un web scraping headless robusto: extrae el contenido de texto principal de páginas web y genera Markdown, texto o HTML para una integración fluida con IA y automatización.

Características principales

• Scraping con navegador headless (Playwright, BeautifulSoup, Markdownify)

• Genera Markdown, texto o HTML

• Diseñado para integración MCP (Model Context Protocol) stdio/JSON-RPC

• Transporte dual: stdio (predeterminado) y HTTP transmitible para modo de servicio compartido

• Pool de navegadores persistente: Chromium permanece activo entre solicitudes para un scraping rápido

• DOM wait inteligente: Estabilización de contenido basada en MutationObserver en lugar de esperas fijas

• Dockerizado, con imágenes preconstruidas

• Configurable mediante variables de entorno

• Manejo robusto de errores (tiempos de espera, errores HTTP, Cloudflare, etc.)

• Limitación de tasa por dominio

• Fácil integración con herramientas de IA e IDEs (Cursor, Claude Desktop, Continue, JetBrains, Zed, etc.)

• Instalación con un clic para Cursor, instalador interactivo para Claude

Related MCP server: Fetcher MCP

Inicio rápido

Ejecutar con Docker (modo stdio — un contenedor por cliente)

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

Ejecutar como servicio HTTP compartido (un contenedor, múltiples clientes)

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

O con Docker Compose:

docker compose --profile service up -d

Instalación con un clic (Cursor IDE)

Modos de transporte

stdio (predeterminado)

Cada cliente MCP inicia su propio contenedor mediante docker run -i. Simple, sin configuración, funciona con cualquier cliente MCP.

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

HTTP transmitible (servicio compartido)

Ejecute un contenedor persistente que sirva a múltiples clientes MCP a través de HTTP. Ahorra recursos al ejecutar múltiples instancias de herramientas de IA (por ejemplo, múltiples sesiones de Claude Code).

Inicie el servicio:

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

Conéctese desde su cliente MCP:

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

Integración con herramientas de IA e IDEs

Este servicio admite la integración con una amplia gama de herramientas de IA e IDEs que implementan el Model Context Protocol (MCP). A continuación, se muestran ejemplos de configuración listos para usar para los entornos más populares. Reemplace la imagen/etiqueta según sea necesario para compilaciones personalizadas.

Cursor IDE

Agréguelo a su .cursor/mcp.json (nivel de proyecto) o ~/.cursor/mcp.json (global):

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

Claude Desktop

Agréguelo a su configuración MCP de Claude Desktop (normalmente claude_desktop_config.json):

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

Claude Code

Agréguelo a su .mcp.json o ~/.claude.json global:

Modo stdio (un contenedor por sesión):

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

Modo HTTP (servicio compartido — inicie el servicio primero):

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

Continue (Plugin de VSCode/JetBrains)

Agréguelo a su continue.config.json o mediante la configuración MCP del plugin de Continue:

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

IntelliJ IDEA (Asistente de IA de JetBrains)

Vaya a Settings > Tools > AI Assistant > Model Context Protocol (MCP) y agregue un nuevo servidor. Use:

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

Zed Editor

Agréguelo a su configuración MCP de Zed (consulte la documentación de Zed para la ruta exacta):

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

Uso

Servidor MCP (Herramienta/Prompt)

Este web scrapper se utiliza como una herramienta MCP (Model Context Protocol), lo que permite que sea utilizado directamente por modelos de IA u otras automatizaciones.

Herramienta: scrape_web

Parámetros:

• url (cadena, requerido): La URL a scrapear

• max_length (entero, opcional): Longitud máxima del contenido devuelto (predeterminado: ilimitado)

• timeout_seconds (entero, opcional): Tiempo de espera en segundos para la carga de la página (predeterminado: 30)

• user_agent (cadena, opcional): Cadena de User-Agent personalizada pasada directamente al navegador (predeterminado: un agente aleatorio)

• wait_for_network_idle (booleano, opcional): Esperar a que la actividad de red se estabilice antes de scrapear (predeterminado: true)

• custom_elements_to_remove (lista de cadenas, opcional): Elementos HTML adicionales (selectores CSS) a eliminar antes de la extracción

• grace_period_seconds (flotante, opcional): Tiempo de espera para el renderizado JS después de la navegación. Utiliza MutationObserver para una detección inteligente. Establezca en 0 para omitir por completo. (predeterminado: 0.5)

• output_format (cadena, opcional): markdown, text o html (predeterminado: markdown)

• click_selector (cadena, opcional): Si se proporciona, hace clic en el elemento que coincide con este selector después de la navegación y antes de la extracción

Retorna:

• Contenido con formato Markdown extraído de la página web, como una cadena

• Los errores se informan como cadenas que comienzan con [ERROR] ...

Ejemplo: Uso de click_selector y 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"
}

Prompt: scrape

Parámetros:

• url (cadena, requerido): La URL a scrapear

• output_format (cadena, opcional): markdown, text o html (predeterminado: markdown)

Retorna:

• Contenido extraído de la página web en el formato elegido

Nota:

• Markdown se devuelve de forma predeterminada, pero se puede solicitar texto o HTML a través de output_format.

• El scrapper no verifica robots.txt e intentará obtener cualquier URL proporcionada.

• No se incluye ninguna API REST o herramienta CLI; esta es una herramienta pura MCP stdio/JSON-RPC.

• El scrapper siempre extrae el contenido completo de <body> de las páginas web, aplicando solo la eliminación de ruido esencial (eliminando script, style, nav, footer, aside, header y etiquetas similares que no son de contenido). El scrapper detecta y maneja las pantallas de desafío de Cloudflare, devolviendo una cadena de error específica.

Configuración

Puede anular la mayoría de las opciones de configuración utilizando variables de entorno:

Configuración principal

• DEFAULT_TIMEOUT_SECONDS: Tiempo de espera para cargas de página y navegación (predeterminado: 30)

• DEFAULT_MIN_CONTENT_LENGTH: Longitud mínima de contenido para texto extraído (predeterminado: 100)

• DEFAULT_MIN_CONTENT_LENGTH_SEARCH_APP: Longitud mínima de contenido para dominios search.app (predeterminado: 30)

• DEFAULT_MIN_SECONDS_BETWEEN_REQUESTS: Retraso mínimo entre solicitudes al mismo dominio (predeterminado: 2)

• DEFAULT_GRACE_PERIOD_SECONDS: Período de gracia predeterminado para renderizado JS (predeterminado: 0.5)

• DEBUG_LOGS_ENABLED: Establezca en true para habilitar registros de nivel de depuración (predeterminado: false)

Pool de navegadores

• BROWSER_POOL_ENABLED: Habilitar pool de navegadores persistente (predeterminado: true). Establezca en false para el inicio del navegador por solicitud (comportamiento original).

• BROWSER_POOL_SIZE: Número de instancias de Chromium a mantener activas (predeterminado: 2). Cada instancia utiliza ~100-200MB de RAM.

Transporte

• MCP_TRANSPORT: Modo de transporte — stdio o streamable-http (predeterminado: stdio)

• MCP_HTTP_PORT: Puerto del servidor HTTP cuando se usa transporte streamable-http (predeterminado: 8080)

• MCP_HTTP_HOST: Dirección de enlace del servidor HTTP (predeterminado: 0.0.0.0)

Bypass de Cloudflare

• CAPTCHA_API_KEY: Clave API para el servicio de resolución de captcha. Cuando se establece, los desafíos de Cloudflare Turnstile se resuelven automáticamente. Cuando está vacío (predeterminado), las páginas protegidas por CF devuelven un error.

• CAPTCHA_PROVIDER: Proveedor de resolución de captcha — 2captcha, capsolver o capmonster (predeterminado: 2captcha)

• CAPTCHA_BASE_URL: Endpoint de API del resolvedor personalizado (predeterminado: utiliza la URL oficial del proveedor)

• CAPTCHA_TIMEOUT: Tiempo de espera en segundos para la resolución de captcha (predeterminado: 120)

Configuración de pruebas

• DEFAULT_TEST_REQUEST_TIMEOUT: Tiempo de espera para solicitudes de prueba (predeterminado: 10)

• DEFAULT_TEST_NO_DELAY_THRESHOLD: Umbral para omitir retrasos artificiales en las pruebas (predeterminado: 0.5)

Manejo de errores y limitaciones

• El scrapper detecta y devuelve errores por fallos de navegación, tiempos de espera, errores HTTP (incluido 404) y desafíos anti-bot de Cloudflare.

• La limitación de tasa se aplica por dominio (predeterminado: 2 segundos entre solicitudes).

• Bypass de Cloudflare: Utiliza Patchright (anti-detección a nivel de CDP) para evasión pasiva. La mayoría de los sitios protegidos por CF se scrapean sin activar un desafío. Cuando se activa un desafío Turnstile y se establece CAPTCHA_API_KEY, se resuelve automáticamente a través de una API de terceros.

• Limitaciones:

  • Sin API REST o herramienta CLI (solo MCP stdio/JSON-RPC)

  • Sin soporte para contenido que no sea HTML (PDF, imágenes, etc.)

  • Sin autenticación o gestión de sesiones para páginas protegidas

  • No destinado a scrapear a gran escala o violar los términos del sitio

Desarrollo y pruebas

Ejecución de pruebas (Docker Compose)

Todas las pruebas deben ejecutarse usando Docker Compose. No ejecute pruebas fuera de Docker.

• Todas las pruebas:

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

• Solo pruebas del servidor MCP:

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

• Solo pruebas del scrapper:

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

Ejecución de benchmarks

docker compose run --rm benchmark

Los resultados se almacenan en benchmarks/RESULTS.md.

Contribución

¡Las contribuciones son bienvenidas! Por favor, abra issues o pull requests para correcciones de errores, características o mejoras. Si planea realizar cambios significativos, abra un issue primero para discutir su propuesta.

Licencia

Este proyecto está bajo la Licencia MIT.