PyreCrawl

13 MCP tools for AI agents: scrape, extract, crawl, map, search, academic papers (arXiv + Crossref), batch scrape, deep research, monitor page changes, persistent browser session, cache control. 3-tier auto-fallback ladder with free Cloudflare bypass, no API keys. Self-hosted Firecrawl alternative. `uvx pyrecrawl serve`

GitHub

Experimente este MCPPatrocinado

Documentação

🔥 PyreCrawl — Superpoderes de Navegação Web para Seu Agente de IA

Um único comando dá a qualquer agente de IA a web inteira. Raspe, extraia, rastreie, mapeie e pesquise — auto-hospedado, sem chaves de API, sem limites de taxa, sem assinatura.

PyreCrawl fala MCP (Model Context Protocol), a interface padrão de ferramentas para Claude, Cursor, VS Code, Codex, OpenCode, Hermes e qualquer agente compatível com MCP.

Uma escada inteligente de fallback automático sempre escolhe o método mais barato que funciona:

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)

⚡ Ferramentas expostas

Ferramenta	O que faz
`scrape(url, prefer="auto")`	URL única → markdown pronto para LLM
`extract(url, schema)`	Raspagem + extração estruturada (esquema JsonCss)
`map_site(root, include_pattern=None, limit=200)`	Enumera todas as URLs internas
`crawl(root, max_pages=5, prefer="auto", include_paths=None, exclude_paths=None, max_depth=0)`	Rastreamento multi-página com filtros de caminho + profundidade BFS real
`document(url)`	PDF/DOCX/PPTX → markdown (sem navegador, extras opcionais `[docs]`)
`search(query, limit=10)`	Pesquisa web via DuckDuckGo HTML (sem chave de API)
`search_papers(query, limit=8, source="arxiv", category=None)`	Pesquisa acadêmica via arXiv + Crossref (sem chave de API) — alimente `pdf_url` em `document`
`batch_scrape(urls[], ...)`	Muitas URLs em UMA chamada — paralelo, deduplicado, ciente de cache
`deep_research(query, limit=5, scrape_top=3)`	Pesquisa → pacote de evidências com citações [n] (sem síntese de LLM — seu agente faz isso)
`monitor(url, action, css_selector=None)`	Detecção de mudanças com snapshots persistidos + diff unificado
`session(session, action, ...)`	Sessão de navegador persistente (cookies mantidos) — muros de login, fluxos multi-etapa, capturas de tela
`cache(action)`	Inspecionar/limpar/habilitar/desabilitar o cache de resposta HTTP
`health()`	Versões + verificação de sanidade de importação

Recursos MCP (estado somente leitura sem chamada de ferramenta): pyrecrawl://cache/stats · pyrecrawl://sessions · pyrecrawl://monitors

Prompts MCP (playbooks prontos): research(topic) · rag_ingest(site) · watch_page(url)

Flags de ambiente

Variável	Padrão	Efeito
`PYRECRAWL_CACHE`	desligado	`1` = LRU em memória (128 páginas), ou um caminho de diretório (reservado para modo disco)
`PYRECRAWL_CACHE_TTL`	`900`	Tempo de vida da entrada de cache em segundos
`PYRECRAWL_MONITOR_DIR`	`~/.pyrecrawl/monitors`	Onde os snapshots do monitor persistem

Opções de prefer: "auto" (escada padrão) · "fast" (somente HTTP) · "stealth" (bypass CF) · "llm" (processamento profundo).

🚀 Instalar e Usar (uma linha)

1. Instalar

UV (recomendado — um comando, zero configuração de Python)

UV é um gerenciador de pacotes Python rápido que cuida do próprio Python — sem necessidade de instalar Python separadamente. Obtenha uma 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"

Saiba mais sobre UV →

Depois execute PyreCrawl diretamente — sem venv, sem pip install, sem download de Python:

uvx pyrecrawl@latest

Ou via uv tool install (persistente, recomendado para uso regular)

uv tool install pyrecrawl

Ou via pipx (alternativa)

pipx install pyrecrawl

Ou via pip em um venv

pip install pyrecrawl

2. Motores de navegador únicos

pyrecrawl setup

Isso instala Chromium + motores de navegador stealth (~2 min, uma única vez).

3. Registre com seu 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 suportados: claude-desktop, claude-code, cursor, vscode, codex, opencode, hermes.

4. Comece a conversar

Após instalar + registrar, reinicie seu agente (ou inicie uma nova sessão). Depois pergunte:

"Raspe https://example.com e resuma."

As ferramentas aparecem como mcp_pyrecrawl_scrape, mcp_pyrecrawl_extract, mcp_pyrecrawl_map_site, mcp_pyrecrawl_crawl, mcp_pyrecrawl_search, mcp_pyrecrawl_health.

📚 Configuração manual (se `pyrecrawl install` não corresponder à sua configuração)

Claude Desktop

Arquivo de configuração

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

Arquivo de configuração: .mcp.json com escopo de projeto

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

Cursor

Arquivo de configuração: ~/.cursor/mcp.json

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

VS Code / Copilot

Arquivo de configuração: .vscode/mcp.json (com escopo de projeto)

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

Codex CLI

Arquivo de configuração: ~/.codex/config.toml

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

OpenCode

Arquivo de configuração: ~/.config/opencode/opencode.json

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

Hermes

Arquivo de configuração

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 deve estar no PATH. Se não estiver, use o caminho completo para uvx.exe (ex.: C:\Users\<you>\AppData\Local\hermes\bin\uvx.exe).

🧠 Como a escada escolhe

PyreCrawl executa cada solicitação através de três camadas, parando na primeira que retorna um resultado completo e pronto para LLM:

Preocupação	Camada rápida	Camada stealth	Camada profunda
Página HTML estática	✅ ~200ms	—	—
Protegido por Cloudflare	❌	✅ Solucionador Turnstile	—
SPA com muito JS	❌	✅ Chromium real	—
Dados DOM ao vivo (entrada `.value`, estado JS)	❌	✅ parâmetro `js`	—
Markdown pronto para LLM + citações	—	—	✅ BM25, fit-markdown
Extração estruturada (esquema CSS)	—	—	✅
Rastreamento profundo (BFS/DFS/BestFirst)	—	—	✅ adaptativo

O agente nunca precisa escolher. prefer="auto" faz isso a cada chamada.

Dados DOM ao vivo com `js` e `wait_for`

Alguns sites mantêm os dados que você quer em uma propriedade do DOM (ex.: o .value de um <input>) que o JS escreve após um XHR — isso nunca aparece no HTML serializado. A ferramenta scrape aceita dois parâmetros da camada stealth exatamente para isso:

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

wait_for — uma expressão de predicado JS consultada até ser verdadeira (limitada por timeout). Use-a em vez de adivinhar um sleep para qualquer coisa que chegue assincronamente.
js — uma expressão JS avaliada quando a página estabiliza; o valor retorna em meta.js_result. Erros são capturados em meta.js_error (o resultado da página ainda é retornado, nunca uma falha).

📊 Comparado ao Firecrawl (hospedado)

	Firecrawl	PyreCrawl
Custo	Grátis 1k/mês, depois $16–333/mês	Grátis, auto-hospedado
Suporte a LLM local	❌	✅ Ollama / qualquer LLM
Bypass Cloudflare	✅ (Fire-Engine, pago)	✅ (grátis, integrado)
Markdown + BM25	✅	✅
Auto-hospedado	❌	✅
Pesquisa de artigos acadêmicos	❌	✅ arXiv + Crossref (`search_papers`)
API de pesquisa hospedada	✅ /search	⚠️ DuckDuckGo HTML + arXiv/Crossref (sem chave)

🔧 Desenvolvimento

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

Executar testes

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

📦 Publicar

Somente mantenedores:

git tag v0.8.0
git push origin v0.8.0

GitHub Actions compila + envia para PyPI via publicação confiável.

🔔 Fique atualizado

PyreCrawl verifica PyPI a cada inicialização e reporta a versão mais recente — seu agente MCP vê isso automaticamente via a resposta da ferramenta health() e pode notificá-lo inline.

Para verificar manualmente:

pyrecrawl version

Para atualizar:

pyrecrawl update   # runs: uv tool upgrade pyrecrawl

Receba notificações de novos lançamentos: clique em Watch → Releases only no repositório GitHub para receber notificações por e-mail quando uma nova versão for publicada.

📜 Desinstalar

# Remove from all agent configs
pyrecrawl uninstall

# Remove the package
uv tool uninstall pyrecrawl

🛡️ Licença

MIT — veja LICENSE.

🙏 Créditos

Construído sobre os ombros de Scrapling e Crawl4AI — ambos MIT, ambos excelentes.