PyreCrawl

🔥 PyreCrawl — Superpoderes de Navegación Web para tu Agente de IA

Un solo comando le da a cualquier agente de IA toda la web. Extrae, procesa, rastrea, mapea y busca — autoalojado, sin claves de API, sin límites de velocidad, sin suscripción.

PyreCrawl habla MCP (Protocolo de Contexto de Modelo), la interfaz estándar de herramientas para Claude, Cursor, VS Code, Codex, OpenCode, Hermes y cualquier agente compatible con MCP.

Una escalera inteligente de respaldo automático siempre elige el método más económico que tenga éxito:

fast HTTP
    │  (403/503/Cloudflare challenge or empty body)
    ▼
stealth browser (real Chromium + Cloudflare solver)
    │  (still blocked, or the page needs full JS rendering)
    ▼
deep processing (LLM-ready markdown, citations, structured extraction)

⚡ Herramientas expuestas

Herramienta	Qué hace
scrape(url, prefer="auto")	URL única → markdown listo para LLM
extract(url, schema)	Extracción + extracción estructurada (esquema JsonCss)
map_site(root, include_pattern=None, limit=200)	Enumera todas las URLs internas
crawl(root, max_pages=5, prefer="auto", include_paths=None, exclude_paths=None, max_depth=0)	Rastreo multipágina con filtros de ruta + profundidad BFS real
document(url)	PDF/DOCX/PPTX → markdown (sin navegador, extras opcionales [docs])
search(query, limit=10)	Búsqueda web vía DuckDuckGo HTML (sin clave de API)
search_papers(query, limit=8, source="arxiv", category=None)	Búsqueda académica vía arXiv + Crossref (sin clave de API) — alimenta pdf_url en document
batch_scrape(urls[], ...)	Muchas URLs en UNA llamada — paralelo, deduplicado, consciente de caché
deep_research(query, limit=5, scrape_top=3)	Búsqueda → paquete de evidencia con citas [n] (sin síntesis de LLM — tu agente hace eso)
monitor(url, action, css_selector=None)	Detección de cambios con instantáneas persistentes + diff unificado
session(session, action, ...)	Sesión de navegador persistente (cookies conservadas) — muros de inicio de sesión, flujos de varios pasos, capturas de pantalla
cache(action)	Inspeccionar/limpiar/habilitar/deshabilitar la caché de respuestas HTTP
health()	Versiones + verificación de importación

Recursos MCP (estado de solo lectura sin llamada de herramienta): pyrecrawl://cache/stats · pyrecrawl://sessions · pyrecrawl://monitors

Indicaciones MCP (manuales listos para usar): research(topic) · rag_ingest(site) · watch_page(url)

Banderas de entorno

Variable	Predeterminado	Efecto
PYRECRAWL_CACHE	off	1 = LRU en memoria (128 páginas), o una ruta de directorio (reservado para modo disco)
PYRECRAWL_CACHE_TTL	900	Vida útil de la entrada de caché en segundos
PYRECRAWL_MONITOR_DIR	~/.pyrecrawl/monitors	Dónde persisten las instantáneas del monitor

Opciones de prefer: "auto" (escalera predeterminada) · "fast" (solo HTTP) · "stealth" (bypass de CF) · "llm" (procesamiento profundo).

---

🚀 Instalar y Usar (una línea)

1. Instalar

UV (recomendado — un comando, cero configuración de Python)

UV es un gestor de paquetes de Python rápido que maneja Python en sí mismo — no necesitas instalar Python por separado. Consíguelo una vez:

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Aprende más sobre UV →

Luego ejecuta PyreCrawl directamente — sin venv, sin pip install, sin descarga de Python:

uvx pyrecrawl@latest

O vía instalación de herramienta uv (persistente, recomendado para uso regular)

uv tool install pyrecrawl

O vía pipx (alternativa)

pipx install pyrecrawl

O vía pip en un venv

pip install pyrecrawl

2. Motores de navegador de una sola vez

pyrecrawl setup

Esto instala Chromium + motores de navegador sigilosos (~2 min, una sola vez).

3. Regístrate con tu agente de IA

# Auto-detect installed agents and write their MCP configs
pyrecrawl install

# Or target specific agents
pyrecrawl install claude-desktop cursor

# Dry-run to preview what would change
pyrecrawl install --dry-run

Agentes compatibles: claude-desktop, claude-code, cursor, vscode, codex, opencode, hermes.

4. Comienza a chatear

Después de instalar + registrar, reinicia tu agente (o inicia una nueva sesión). Luego pregunta:

"Extrae https://example.com y resúmelo."

Las herramientas aparecen como mcp_pyrecrawl_scrape, mcp_pyrecrawl_extract, mcp_pyrecrawl_map_site, mcp_pyrecrawl_crawl, mcp_pyrecrawl_search, mcp_pyrecrawl_health.

---

📚 Configuración manual (si pyrecrawl install no coincide con tu configuración)

Claude Desktop

Archivo de configuración

• Linux: ~/.config/Claude/claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %AppData%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "pyrecrawl": {
      "command": "uvx",
      "args": ["--from", "pyrecrawl", "pyrecrawl", "serve"]
    }
  }
}

Claude Code

Archivo de configuración: .mcp.json a nivel de proyecto

{
  "mcpServers": {
    "pyrecrawl": {
      "command": "uvx",
      "args": ["--from", "pyrecrawl", "pyrecrawl", "serve"]
    }
  }
}

Cursor

Archivo de configuración: ~/.cursor/mcp.json

{
  "mcpServers": {
    "pyrecrawl": {
      "command": "uvx",
      "args": ["--from", "pyrecrawl", "pyrecrawl", "serve"]
    }
  }
}

VS Code / Copilot

Archivo de configuración: .vscode/mcp.json (a nivel de proyecto)

{
  "servers": {
    "pyrecrawl": {
      "command": "uvx",
      "args": ["--from", "pyrecrawl", "pyrecrawl", "serve"],
      "type": "stdio"
    }
  }
}

Codex CLI

Archivo de configuración: ~/.codex/config.toml

[mcp_servers.pyrecrawl]
command = "uvx"
args = ["--from", "pyrecrawl", "pyrecrawl", "serve"]

OpenCode

Archivo de configuración: ~/.config/opencode/opencode.json

{
  "mcp": {
    "pyrecrawl": {
      "type": "local",
      "command": ["uvx", "--from", "pyrecrawl", "pyrecrawl", "serve"],
      "enabled": true
    }
  }
}

Hermes

Archivo de configuración

• Linux/macOS: ~/.hermes/config.yaml
• Windows: %LocalAppData%\hermes\config.yaml

mcp_servers:
  pyrecrawl:
    command: uvx
    args:
      - --from
      - pyrecrawl
      - pyrecrawl
      - serve
    enabled: true

Nota para Windows: uvx debe estar en PATH. Si no, usa la ruta completa a uvx.exe (por ejemplo, C:\Users\<you>\AppData\Local\hermes\bin\uvx.exe).

---

🧠 Cómo elige la escalera

PyreCrawl ejecuta cada solicitud a través de tres niveles, deteniéndose en el primero que devuelva un resultado completo y listo para LLM:

Preocupación	Nivel rápido	Nivel sigiloso	Nivel profundo
Página HTML estática	✅ ~200ms	—	—
Protegida por Cloudflare	❌	✅ Solucionador de Turnstile	—
SPA con mucho JS	❌	✅ Chromium real	—
Datos DOM en vivo (entrada .value, estado JS)	❌	✅ parámetro js	—
Markdown listo para LLM + citas	—	—	✅ BM25, fit-markdown
Extracción estructurada (esquema CSS)	—	—	✅
Rastreo profundo (BFS/DFS/BestFirst)	—	—	✅ adaptativo

El agente nunca tiene que elegir. prefer="auto" lo hace en cada llamada.

Datos DOM en vivo con js y wait_for

Algunos sitios mantienen los datos que quieres en una propiedad del DOM (por ejemplo, el .value de un <input>) que JS escribe después de un XHR — nunca aparece en el HTML serializado. La herramienta scrape acepta dos parámetros de nivel sigiloso exactamente para esto:

{
  "url": "https://temp-mail.org/id",
  "prefer": "stealth",
  "wait_for": "document.getElementById('mail').value.includes('@')",
  "js": "document.getElementById('mail').value"
}

• wait_for — una expresión de predicado JS consultada hasta que sea verdadera (limitada por timeout). Úsala en lugar de adivinar un retraso para cualquier cosa que llegue de forma asíncrona.
• js — una expresión JS evaluada una vez que la página se asiente; el valor regresa en meta.js_result. Los errores se capturan en meta.js_error (el resultado de la página aún se devuelve, nunca un bloqueo).

---

📊 Comparado con Firecrawl (alojado)

	Firecrawl	PyreCrawl
Costo	Gratis 1k/mes, luego $16–333/mes	Gratis, autoalojado
Soporte de LLM local	❌	✅ Ollama / cualquier LLM
Bypass de Cloudflare	✅ (Fire-Engine, de pago)	✅ (gratis, integrado)
Markdown + BM25	✅	✅
Autoalojado	❌	✅
Búsqueda de artículos académicos	❌	✅ arXiv + Crossref (search_papers)
API de búsqueda alojada	✅ /search	⚠️ DuckDuckGo HTML + arXiv/Crossref (sin clave)

---

🔧 Desarrollo

git clone https://github.com/SanggonBoy/PyreCrawl.git
cd PyreCrawl
uv venv --python 3.12 .venv
source .venv/Scripts/activate  # Windows; or .venv/bin/activate on macOS/Linux
uv pip install -e ".[dev]"
python -m playwright install chromium
scrapling install

Ejecutar pruebas

python scripts/selfcheck.py   # real-network smoke test
python scripts/probe_stdio.py # stdio JSON-RPC probe

---

📦 Publicar

Solo mantenedores:

git tag v0.8.0
git push origin v0.8.0

GitHub Actions compila y sube a PyPI vía publicación confiable.

---

🔔 Mantente al día

PyreCrawl verifica PyPI en cada inicio e informa la versión más reciente — tu agente MCP ve esto automáticamente vía la respuesta de la herramienta health() y puede notificarte en línea.

Para verificar manualmente:

pyrecrawl version

Para actualizar:

pyrecrawl update   # runs: uv tool upgrade pyrecrawl

Recibe notificaciones de nuevos lanzamientos: haz clic en Watch → Solo lanzamientos en el repositorio de GitHub para recibir notificaciones por correo electrónico cuando se publique una nueva versión.

---

📜 Desinstalar

# Remove from all agent configs
pyrecrawl uninstall

# Remove the package
uv tool uninstall pyrecrawl

---

🛡️ Licencia

MIT — consulta LICENSE.

🙏 Créditos

Construido sobre los hombros de Scrapling y Crawl4AI — ambos MIT, ambos excelentes.