site-crawler-mcp

Un servidor MCP de rastreo completo del sitio construido sobre crawl4ai (Apache-2.0). Rastrea todos los enlaces internos de un sitio web como un spider de motor de búsqueda (BFS), filtra páginas por fecha de publicación / título / URL, y puede operar sobre páginas rastreadas (resumir, hacer clic en enlaces, descargar archivos). Los resultados se devuelven como JSON y se persisten en SQLite para su reutilización por cualquier proyecto.

Resumen en español: un MCP de rastreo completo de enlaces internos «como el crawler de Google». Basado en crawl4ai con encapsulación propia, admite recorrido BFS completo del sitio, filtrado por fecha/título/URL, operaciones en páginas (resumen LLM/clic en enlaces/descarga de archivos), resultados en JSON + persistencia en SQLite. Regístrelo en Reasonix / Claude Desktop / Cursor o cualquier cliente MCP para reutilizarlo globalmente.

Características

• ✅ Rastreo BFS completo del sitio — recorre todos los enlaces internos (max_depth / max_page controlables)

• ✅ Filtro de tiempo — extrae la fecha de publicación de metadatos de página / JSON-LD / URL primero, recurre a la hora de rastreo cuando no está disponible (resultado etiquetado con time_source)

• ✅ Filtro de título — incluir/excluir por palabra clave en el título (sin distinción de mayúsculas/minúsculas)

• ✅ Filtros de patrón URL y dominio — coincidencia glob/regex de URL, restricción al mismo dominio

• ✅ Rastreo educado — respeta robots.txt y limita la tasa por defecto (configurable)

• ✅ Operaciones en páginas — resumen LLM (LiteLLM: DeepSeek / GLM / OpenAI…, fallback local), hacer clic en un enlace específico (selector CSS o texto del enlace), descargar archivos

• ✅ Persistencia en SQLite — herramienta query_crawls para reutilizar datos rastreados en proyectos posteriores

Related MCP server: Spider MCP Server

Herramientas

Requisitos

• Python ≥ 3.12 (probado en 3.12.13)

• uv recomendado (opcional — también funciona con pip normal)

• Navegadores Playwright: python -m playwright install chromium (o apunte PLAYWRIGHT_BROWSERS_PATH a una instalación de navegador existente)

Instalar y Registrar

# 1. Create environment & install
uv venv .venv --python 3.12
uv pip install --python .venv\Scripts\python.exe crawl4ai "mcp>=1.2,<2"
uv pip install --python .venv\Scripts\python.exe -e .

# 2. Install browser (once)
.venv\Scripts\python.exe -m playwright install chromium

# 3. Register as MCP server (example for Reasonix config.toml)
[[plugins]]
name    = "site-crawler-mcp"
type    = "stdio"
command = "C:\\path\\to\\site-crawler-mcp\\.venv\\Scripts\\python.exe"
args    = ["-m", "site_crawler_mcp.server"]

Para Claude Desktop / Cursor, agregue los mismos command/args bajo mcpServers en sus archivos de configuración.

Inicio Rápido (API de Python)

import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def main():
    params = StdioServerParameters(command="python", args=["-m", "site_crawler_mcp.server"])
    async with stdio_client(params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            res = await session.call_tool("crawl_site", {
                "start_url": "https://example.com",
                "max_depth": 2,
                "max_pages": 20,
                "title_contains": "Example",
            })
            print(res.content[0].text)

asyncio.run(main())

Cómo funciona el filtro de tiempo

Los filtros de URL de crawl4ai solo funcionan sobre las URL, por lo que aquí se implementa el filtrado a nivel de contenido:

1. Poda a nivel de URL — TimeRangeFilter / TitleFilter (patrones de fecha en URL, palabras clave en URL)

2. A nivel de contenido — después de obtener cada página, la fecha de publicación se extrae de <meta property="article:published_time">, JSON-LD datePublished, <time datetime>, o YYYY/MM/DD en la URL. Si no se encuentra ninguna, se usa la hora de rastreo (decisión documentada como time_source).

Cumplimiento

• Respeta robots.txt y límites de tasa por defecto para evitar estresar los sitios de destino o ser bloqueado por IP.

• Para aprendizaje / investigación / sus propios sitios; siga los Términos de Servicio de los sitios de destino y las leyes locales.

Licencia

MIT

Construido sobre crawl4ai (Apache-2.0).