webscout-mcp

Herramientas de búsqueda y recuperación web para agentes de IA, como servidor MCP. Busca, recupera, rastrea y extrae datos estructurados de la web: sin claves API, sin facturación por solicitud, todo permanece en tu máquina.

Instalación

pip install webscout-mcp

Requiere Python 3.10+.

Related MCP server: Crawl4AI RAG MCP Server

Inicio rápido

Añádelo a la configuración de tu cliente MCP (Claude Code, Cursor, Codex, etc.):

{
  "mcpServers": {
    "webscout": {
      "command": "webscout-mcp",
      "args": []
    }
  }
}

Eso es todo. Tu agente obtiene seis herramientas:

• web_search - busca mediante Bing con respaldo automático de DuckDuckGo HTML, sin necesidad de clave

• web_fetch - recupera una página y extrae el artículo principal (markdown/texto/html)

• web_crawl - rastreo BFS concurrente con límites de profundidad y páginas, respeta robots.txt

• web_extract - extrae datos estructurados con selectores CSS, atributos, regex

• cache_stats - inspecciona la caché local

• cache_clear - limpia la caché

Uso desde la línea de comandos

Además de ejecutarse como servidor MCP, puedes usar webscout-mcp directamente desde la línea de comandos:

# Search the web (outputs JSON)
webscout-mcp search "python async libraries" --max-results 5

# Fetch a page (raw content)
webscout-mcp fetch https://example.com --extract --format markdown --raw

# Crawl a site
webscout-mcp crawl https://example.com --depth 2 --pages 10

# Start MCP server (default if no command given)
webscout-mcp serve --transport stdio

Ejemplos de uso

Búsqueda

web_search(query="best python async libraries", max_results=5)

Devuelve resultados estructurados con título, URL, fragmento y qué backend sirvió la solicitud (bing o duckduckgo). Si Bing falla o cambia su marcado, el motor recurre automáticamente a la versión HTML de DuckDuckGo, sin necesidad de configuración.

Recuperar una página

web_fetch(url="https://example.com", extract=true, output_format="markdown")

extract=true ejecuta trafilatura (con respaldo de readability-lxml) para eliminar navegación, anuncios y barras laterales: obtienes contenido de artículo limpio, no HTML crudo.

Extraer datos estructurados

web_extract(
  url="https://example.com/products",
  rules='[
    {"name": "titles", "selector": ".product h2", "multiple": true},
    {"name": "prices", "selector": ".price", "regex": "\\$([\\d.]+)", "multiple": true},
    {"name": "links", "selector": "a.product", "attribute": "href", "multiple": true}
  ]'
)

Cada regla admite selector, attribute, multiple, regex y default.

Rastrear un sitio

web_crawl(seed_url="https://example.com", max_depth=2, max_pages=10, concurrency=5)

Las páginas de cada nivel de profundidad se recuperan de forma concurrente (controlado por concurrency, por defecto 5). El rastreador respeta robots.txt por defecto: las URLs no permitidas se omiten y se cuentan en skipped_robots. La restricción de mismo dominio está activada por defecto.

Uso como biblioteca de Python

import asyncio
from webscout_mcp import Config, Fetcher, SearchEngine

async def main():
    config = Config.from_env()
    config.ensure_dirs()

    fetcher = Fetcher(config)
    result = await fetcher.fetch("https://example.com", extract=True)
    print(result.title)
    print(result.content[:500])
    await fetcher.close()

    search = SearchEngine(config)
    results = await search.search("python async", max_results=5)
    for r in results:
        print(f"{r.position}. {r.title} - {r.url} ({r.backend})")
    await search.close()

asyncio.run(main())

Cómo funciona

• Búsqueda intenta primero con Bing y luego con DuckDuckGo HTML, ambos mediante scraping HTTP directo, sin clave API. Los resultados se almacenan en caché por consulta.

• Recuperación usa httpx con reintentos de retroceso exponencial (todos los errores de httpx + HTTP 5xx), limitación de velocidad por dominio con token-bucket y un límite de contenido de 5 MB.

• Extracción de contenido usa trafilatura como principal y readability-lxml como respaldo automático: las mismas bibliotecas detrás de muchos servicios de lectura posterior.

• Caché es SQLite con TTL y límite de tamaño; las entradas antiguas se eliminan automáticamente. Las recuperaciones y búsquedas repetidas no cuestan nada.

• Rastreo es BFS concurrente con profundidad configurable, número de páginas, concurrencia, restricción de mismo dominio y cumplimiento de robots.txt. Usa el HTML crudo de la recuperación inicial para evitar recuperar cada página dos veces.

• Soporte de proxy enruta todas las solicitudes HTTP/HTTPS a través de un proxy mediante configuración o variables de entorno.

• Registro es estructurado y configurable mediante WEBSCOUT_LOG_LEVEL (DEBUG/INFO/WARNING/ERROR) y WEBSCOUT_LOG_JSON=1 para salida JSON.

Todo se ejecuta localmente. Ningún dato sale de tu máquina.

Configuración

Todos los ajustes tienen valores predeterminados sensatos. Se pueden sobrescribir mediante variables de entorno (prefijo WEBSCOUT_), un archivo de configuración TOML o banderas de línea de comandos.

Archivo de configuración

Crea ~/.config/webscout/config.toml (o $XDG_CONFIG_HOME/webscout/config.toml):

[cache]
ttl = 7200
max_size_mb = 512

[fetch]
timeout = 15.0
max_retries = 3

[proxy]
http = "http://proxy:8080"
https = "http://proxy:8080"

[search]
max_results = 10
backends = ["bing", "duckduckgo"]

[crawler]
max_depth = 2
max_pages = 20
concurrency = 5
respect_robots = true

[logging]
level = "WARNING"
json = false

Las variables de entorno sobrescriben los valores del archivo de configuración.

Variables de entorno

Las banderas de línea de comandos sobrescriben las variables de entorno:

webscout-mcp --cache-ttl 3600 --cache-dir /tmp/webscout serve

Transportes

# stdio (default - works with Claude Code, Cursor, etc.)
webscout-mcp

# SSE (for remote or browser-based clients)
webscout-mcp serve --transport sse --host 0.0.0.0 --port 8000

Registro de cambios

0.3.0

• Soporte de archivo de configuración TOML: configura mediante ~/.config/webscout/config.toml además de variables de entorno

• Soporte de proxy HTTP/HTTPS: enruta todas las solicitudes a través de un proxy

• Extracción de contenido dual: trafilatura como principal, readability-lxml como respaldo automático

• Deduplicación de resultados de búsqueda: URLs duplicadas eliminadas, posiciones renumeradas

• Búsqueda consciente de región: el parámetro region ahora se pasa realmente a Bing y DuckDuckGo

• Rendimiento del rastreador: eliminada la doble recuperación por página: rastreos ~2x más rápidos

• Mejor lógica de reintentos: reintentos en todos los errores de httpx y HTTP 5xx

• Detección de tipo de contenido corregida: detección adecuada de HTML/XML

0.2.0

• Búsqueda multi-backend: Bing + DuckDuckGo HTML con conmutación automática por error

• Rastreador concurrente con paralelismo configurable

• Cumplimiento de robots.txt (configurable, activado por defecto)

• Subcomandos CLI: search, fetch, crawl, serve

• Registro estructurado con formateadores de consola y JSON

• Jerarquía de excepciones personalizada para mejor manejo de errores

• Nueva configuración: WEBSCOUT_SEARCH_BACKENDS, WEBSCOUT_CRAWLER_CONCURRENCY, WEBSCOUT_RESPECT_ROBOTS

0.1.0

• Lanzamiento inicial: web_search, web_fetch, web_crawl, web_extract, cache_stats, cache_clear

• Caché SQLite con TTL y expulsión basada en tamaño

• Limitación de velocidad por dominio con token-bucket

• Reintentos con retroceso exponencial

• Extracción de contenido con trafilatura

Desarrollo

git clone https://github.com/wxs-lang/webscout-mcp.git
cd webscout-mcp
pip install -e ".[dev]"
pytest

Licencia

MIT