Web Scraper MCP

Un servidor autoalojado del Model Context Protocol que ofrece a un cliente LLM (Claude Code, Cursor, ChatGPT) la misma superficie de herramientas que los servicios de scraping de pago — scrape, crawl, map, search, extract, interact, deep_research — ejecutándose completamente en tu propio hardware.

Sin servicios de proxy/CAPTCHA de pago: el anti-bot es autoalojado (Chromium sin interfaz + playwright-stealth, robots.txt, limitación de velocidad cortés). Los sitios endurecidos aún pueden bloquear; ver Limitaciones.

Herramientas

extract y deep_research requieren ANTHROPIC_API_KEY.

Related MCP server: Universal Web Data Extraction Platform

Inicio rápido

uv sync                      # install deps (uses the pinned uv.lock)
uv run playwright install chromium
export SCRAPER_AUTH_TOKEN=$(openssl rand -hex 32)
uv run web-scraper-mcp       # HTTP server on http://127.0.0.1:8000/mcp

Stdio (local, para un cliente de escritorio): SCRAPER_TRANSPORT=stdio uv run web-scraper-mcp.

Docker

La forma más rápida de empezar es descargando la imagen preconstruida desde DockerHub.

# Pull the latest image
docker pull PROG_UP_USERNAME/web-scraper-mcp:latest

# Run the container (with Anthropic / Claude)
docker run -p 8000:8000 \
  -e SCRAPER_AUTH_TOKEN=your_secure_token_here \
  -e ANTHROPIC_API_KEY=sk-ant-api03-... \
  PROG_UP_USERNAME/web-scraper-mcp:latest

# Or run the container over stdio (useful for local MCP clients)
docker run -i --rm \
  -e SCRAPER_TRANSPORT=stdio \
  -e SCRAPER_AUTH_TOKEN=your_secure_token_here \
  PROG_UP_USERNAME/web-scraper-mcp:latest

(Asegúrate de reemplazar PROG_UP_USERNAME con tu nombre de usuario real de DockerHub).

Uso de Modelos Locales (Ollama) y Ventanas de Contexto

Si prefieres ejecutar modelos localmente en lugar de usar la API de Anthropic, el servidor es totalmente compatible con Ollama como backend alternativo para las herramientas extract y deep_research.

docker run -p 8000:8000 \
  -e SCRAPER_AUTH_TOKEN=your_secure_token_here \
  -e SCRAPER_OLLAMA_HOST=http://host.docker.internal:11434 \
  -e SCRAPER_EXTRACT_MODEL=qwen3.5:2b \
  -e SCRAPER_RESEARCH_MODEL=qwen3.5:2b \
  PROG_UP_USERNAME/web-scraper-mcp:latest

[!WARNING] ¡Las ventanas de contexto son críticas! El scraping web produce una cantidad masiva de Markdown. extract puede enviar hasta 100,000 caracteres y deep_research puede enviar hasta 16,000 caracteres al LLM.

Por defecto, Claude maneja contextos masivos de forma nativa. Sin embargo, la ventana de contexto predeterminada de Ollama (num_ctx) a menudo está configurada a solo 2,048 tokens. Si pasas una página enorme de Wikipedia a un modelo local, truncará silenciosamente el prompt (eliminando tus instrucciones) y devolverá cadenas vacías.

Pasamos automáticamente "num_ctx": 32768 a Ollama en las cargas útiles de la API para evitar esta truncación. ¡Asegúrate de que tu máquina local tenga suficiente RAM/VRAM para soportar una ventana de contexto de 32K al usar Ollama!

Registro en un cliente (mcp.json)

Si se ejecuta vía HTTP:

{
  "mcpServers": {
    "web-scraper": {
      "url": "http://127.0.0.1:8000/mcp",
      "headers": { "Authorization": "Bearer your_secure_token_here" }
    }
  }
}

Si se ejecuta vía stdio (Docker):

{
  "mcpServers": {
    "web-scraper": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "SCRAPER_TRANSPORT=stdio",
        "-e", "SCRAPER_OLLAMA_HOST=http://host.docker.internal:11434",
        "-e", "SCRAPER_EXTRACT_MODEL=qwen3.5:2b",
        "-e", "SCRAPER_RESEARCH_MODEL=qwen3.5:2b",
        "PROG_UP_USERNAME/web-scraper-mcp:latest"
      ]
    }
  }
}

Configuración

Todos los ajustes son variables de entorno (prefijo SCRAPER_), o un archivo .env — ver .env.example.

Seguridad

• Protección SSRF — cada URL obtenida (y cada salto de redirección) se resuelve por DNS y se rechaza si apunta a una dirección privada / de bucle local / enlace local / metadatos de nube. El navegador también aborta las solicitudes de subrecursos a IPs privadas.

• Autenticación — token Bearer en el transporte HTTP; enlazar a localhost por defecto.

• Límites de recursos — tamaño de respuesta, tiempo de espera, concurrencia de páginas, límites de páginas/profundidad de rastreo para proteger el host.

• robots.txt + limitación de velocidad activados por defecto.

• Contenedor — se ejecuta como usuario no root; secretos solo mediante variables de entorno.

Cadena de suministro — verificación de la imagen

El CI firma la imagen sin claves con cosign (Sigstore) usando la identidad OIDC de GitLab, y adjunta una atestación SBOM SPDX. Verifica antes de ejecutar:

cosign verify \
  --certificate-oidc-issuer https://gitlab.cri.epita.fr \
  --certificate-identity-regexp 'https://gitlab.cri.epita.fr/enzo.juhel/web-scraper//.*' \
  registry.gitlab.cri.epita.fr/enzo.juhel/web-scraper@sha256:...

Benchmark

benchmarks/run.py puntúa nuestro scrape/extract contra conjuntos de datos públicos y la línea base de Crawl4AI, emitiendo una tarjeta de puntuación (F1/precisión por tipo de página + una sección de Limitaciones). Ejecuta localmente o mediante el trabajo manual de CI benchmark:

uv run python benchmarks/run.py --output scorecard.md

Limitaciones

• Sin proxies/CAPTCHA de pago: los sitios muy protegidos (LinkedIn, Amazon, desafíos de Cloudflare) a veces nos bloquearán. La tarjeta de puntuación del benchmark cuantifica dónde.

• La extracción de contenido principal es fuerte en artículos, más débil en foros / páginas de productos / listados (una propiedad conocida de todos los extractores).

• Estado de rastreo/sesión en memoria — de un solo proceso y un solo usuario por diseño.

Desarrollo

uv run pre-commit install        # local lint/secret hooks
uv run ruff check . && uv run ruff format --check .
uv run mypy src
uv run pytest -q