Crawlforge MCP

28 ferramentas de web scraping, crawling, deep-research e extração autônoma para Claude, Cursor e qualquer cliente MCP.
Markdown limpo e JSON estruturado de qualquer site. Comece com 1.000 créditos grátis — sem necessidade de cartão de crédito.

⭐ Dê uma estrela no GitHub para nos acompanhar — isso realmente ajuda outras pessoas a descobrirem o projeto.

Sumário

• Por que o CrawlForge?
• CrawlForge vs. alternativas
• Início Rápido (2 Minutos)
• Ferramentas Disponíveis
• Preços
• Configuração Avançada
• Exemplos de Uso
• Segurança e Privacidade
• Suporte
• Contribuição

🎯 Por que o CrawlForge?

• 28 ferramentas nativas MCP — scraping, crawling, busca, monitoramento real de posição no SERP do Google, deep research, um agent autônomo, um scrape unificado multi-formato, processamento de documentos, navegação stealth e muito mais, chamáveis diretamente do seu assistente de IA.
• Camada gratuita generosa — 1.000 créditos para começar instantaneamente, sem cartão de crédito. A concessão é única, não mensal, e os créditos nunca expiram.
• LLM local por padrão — extract_with_llm roda com um modelo Ollama local pronto para uso: sem chave de API de LLM, sem custo por token, e seus dados nunca saem da sua máquina. Nuvem (OpenAI/Anthropic) é opcional.
• Saída pronta para LLM — Markdown limpo, JSON estruturado (orientado por schema), capturas de tela, links e metadados em uma única busca.
• agent autônomo — descreva o que você precisa em linguagem natural; ele planeja, coleta e molda uma resposta sob limites rígidos impostos pelo orquestrador (máx. de etapas/URLs/tempo) — sem necessidade de URLs.
• Segurança reforçada — proteção SSRF em cada requisição, lista de permissões de backend com falha segura, lista de ações aprovadas para automação de navegador e controle de créditos por ferramenta.
• Funciona em qualquer lugar que o MCP funcione — Claude Desktop, Claude Code, Cursor e qualquer outro cliente habilitado para MCP, configurado com um único comando.

📊 CrawlForge vs. alternativas

A comparação reflete as capacidades documentadas publicamente no momento da escrita. O CrawlForge é licenciado sob MIT e prioriza MCP — construído para conectar diretamente em assistentes de codificação de IA.

🚀 Início Rápido (2 Minutos)

1. Instale pelo NPM

npm install -g crawlforge-mcp-server

2. Configure Sua Chave de API (obrigatório)

Toda ferramenta exige uma chave de API do CrawlForge — novas contas recebem 1.000 créditos de teste grátis para começar:

npx crawlforge-setup

Isso irá:

• Orientar você na obtenção da sua chave de API gratuita
• Configurar suas credenciais com segurança
• Configurar automaticamente o Claude Code e o Cursor (se instalados)
• Verificar se sua configuração está funcionando

Não tem uma chave de API? Obtenha uma gratuitamente em https://www.crawlforge.dev/signup

Configuração em uma etapa (v4.6.0+): crawlforge init detecta sua chave de API, instala a skill do agente e mescla de forma idempotente o trecho de configuração MCP no Claude Code, Claude Desktop e Cursor. Use crawlforge init --all --yes para configurar cada cliente detectado de forma não interativa.

3. Configure Sua IDE (se não configurada automaticamente)

{
  "mcpServers": {
    "crawlforge": {
      "command": "npx",
      "args": ["-y", "crawlforge-mcp-server"]
    }
  }
}

{
  "mcpServers": {
    "crawlforge": {
      "type": "stdio",
      "command": "crawlforge-mcp"
    }
  }
}

{
  "mcpServers": {
    "crawlforge": {
      "type": "stdio",
      "command": "crawlforge-mcp"
    }
  }
}

export CRAWLFORGE_API_KEY=your_api_key
npm run start:http    # Streamable HTTP endpoint at http://localhost:10000/mcp

Qual comando de inicialização? npx -y crawlforge-mcp-server não requer instalação global e sempre executa a versão publicada (recomendado para Claude Desktop). Para uma instalação global (npm i -g crawlforge-mcp-server), use o binário dedicado crawlforge-mcp — ele resolve no seu PATH, então sobrevive a trocas de versão do Node/nvm. O comando simples crawlforge ainda inicia o servidor quando um cliente MCP o executa via stdio (compatibilidade retroativa para configurações criadas antes da v4.2.5); interativamente, é o CLI — execute crawlforge mcp para iniciar o servidor manualmente.

📊 Ferramentas Disponíveis

O CrawlForge exige uma chave de API do CrawlForge — toda ferramenta é medida e consome créditos. Novas contas recebem 1.000 créditos de teste grátis para começar. Obtenha uma chave em crawlforge.dev/signup.

Todas as Ferramentas (chave de API obrigatória)

Para a referência canônica completa de capacidades (todas as ferramentas, comandos CLI, mecanismos stealth, fluxo de pesquisa), veja SKILL.md.

↑ Voltar ao topo

💳 Preços

Toda ferramenta é medida e exige uma chave de API. Novas contas recebem 1.000 créditos de teste grátis — sem necessidade de cartão de crédito para começar.

Todos os planos incluem:

• Acesso a todas as 28 ferramentas
• Créditos nunca expiram; créditos de planos pagos acumulam mês a mês
• Acesso à API e notificações via webhook

Ver preços completos

🔧 Configuração Avançada

Variáveis de Ambiente

# Optional: Set API key via environment
export CRAWLFORGE_API_KEY="cf_live_your_api_key_here"

# Optional: Custom API endpoint (for enterprise)
export CRAWLFORGE_API_URL="https://api.crawlforge.dev"
# As of v3.0.18, this variable is validated against an allow-list of CrawlForge backend hosts.

# Optional: Local LLM (Ollama) overrides — extract_with_llm, extract_structured
# and deep_research all use Ollama when no cloud key is set
export OLLAMA_BASE_URL="http://localhost:11434"   # default; set https://ollama.com for Ollama Cloud
export OLLAMA_DEFAULT_MODEL="gemma3:4b"            # optional; unset = pick the best installed model automatically
                                                   # deep_research judges claims with gemma3:12b when it is installed (ollama pull gemma3:12b);
                                                   # conflict detection is on only with that model, or a cloud provider
export OLLAMA_EMBEDDING_MODEL="nomic-embed-text"   # default: OLLAMA_DEFAULT_MODEL; used for semantic ranking in deep_research
export OLLAMA_API_KEY="..."                        # only for authenticated endpoints (required by Ollama Cloud; a local instance needs none)
export DISABLE_OLLAMA="true"                       # skip Ollama entirely and use CSS/keyword fallbacks

# Optional: Cloud LLM keys — only needed when you pass provider: "openai" or "anthropic"
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."

# Optional: limit which tools this client sees — by name, by group, or both (comma-separated)
export CRAWLFORGE_TOOLS="scrape,search_web,extract_content"
export CRAWLFORGE_TOOL_GROUPS="basic,search,scrape"   # unset = all tools; unknown names/groups are ignored with a warning

# Optional: deep_research stealth extraction fallback (v4.6.6) — see below
export RESEARCH_STEALTH_ENGINE="auto"      # auto (default) | camoufox | chromium
export RESEARCH_STEALTH_FALLBACK="true"    # set to "false" to disable entirely
export RESEARCH_MAX_STEALTH_RETRIES="8"    # cap on stealth retries per research run

Recursos da Especificação MCP

O CrawlForge acompanha a especificação MCP atual (2025-06-18) além de extensões experimentais selecionadas:

• Saída estruturada — scrape, map_site, serp_rank, reddit_search, search_web, extract_structured e crawl_deep retornam structuredContent analisável por máquina junto com o texto usual, validado contra um outputSchema publicado; clientes legados continuam funcionando com o texto.
• Erros autocorrigíveis — entrada de ferramenta inválida agora retorna como um resultado isError: true que o modelo chamador pode ler e tentar novamente, em vez de um erro bruto de protocolo JSON-RPC.
• Schemas de ferramenta JSON Schema 2020-12, ordenação determinística de tools/list (amigável ao cache de prompt do cliente) e dicas de resultados armazenáveis em cache em ferramentas somente leitura.
• Ícones no servidor, suas ferramentas e seus prompts.
• Tarefas assíncronas (experimental) nas quatro ferramentas de longa duração — crawl_deep, batch_scrape, deep_research, agent — para clientes que suportam polling; resultados síncronos ainda são retornados para clientes que não suportam.

Veja docs/mcp-spec-adoption.md para exemplos no nível de protocolo e notas de compatibilidade com clientes.

Início rápido com LLM local (extract_with_llm com Ollama)

extract_with_llm usa um modelo Ollama local por padrão — sem chave de provedor de LLM, sem custos de LLM por token e sem dados saindo da sua máquina (o custo em créditos do CrawlForge ainda se aplica).

# 1. Install Ollama:  https://ollama.com
# 2. Pull any model from https://ollama.com/library
ollama pull llama3.2

# 3. Discover what's installed (from your MCP client)
#    list_ollama_models()

# 4. Extract — defaults to Ollama with the model from step 2
#    extract_with_llm({ url: "https://example.com", prompt: "…", model: "llama3.2" })

Extração furtiva para deep_research (Camoufox)

deep_research tenta automaticamente novamente fontes que bloqueiam o caminho normal de busca (Reddit, Quora, fóruns e páginas protegidas por Cloudflare/DataDome retornam HTTP 403) por meio de um navegador real com fingerprint, e então reextrai do HTML renderizado. É limitado (RESEARCH_MAX_STEALTH_RETRIES, padrão 8, mais um timeout por página) e preguiçoso — a pilha do navegador só é carregada quando uma fonte está realmente bloqueada.

Seleção do mecanismo (RESEARCH_STEALTH_ENGINE):

• auto (padrão) — prefere Camoufox (anti-detecção Firefox), com fallback para stealth Chromium e, em seguida, busca simples.
• camoufox — força Camoufox.
• chromium — força o mecanismo stealth Chromium.

Chromium headless não consegue resolver desafios modernos (Cloudflare Turnstile, DataDome) — Camoufox consegue. Em testes, ele recuperou páginas do Quora e Trustpilot que estavam totalmente bloqueadas. Para habilitá-lo, instale a dependência opcional e execute a busca binária única:

# Camoufox is declared as an optional dependency, so a normal install already pulls it.
# If you installed with --no-optional, add it explicitly:
npm install camoufox

# One-time download of the Camoufox Firefox binary (~130 MB):
npx camoufox fetch

Sem o binário do Camoufox, deep_research silenciosamente faz fallback para stealth Chromium e depois para busca simples — sem erros, apenas menor recuperação em sites altamente protegidos. Desative todo o fallback com RESEARCH_STEALTH_FALLBACK=false.

Nota: Bloqueios rígidos de reputação de IP (por exemplo, o edge 403 do Reddit) resistem ao stealth headless de qualquer IP e exigem proxies residenciais/móveis, que o CrawlForge não fornece. Consulte docs/stealth-engines.md para detalhes.

Configuração Manual

Sua configuração está armazenada em ~/.crawlforge/config.json:

{
  "apiKey": "cf_live_...",
  "userId": "user_...",
  "email": "you@example.com"
}

📖 Exemplos de Uso

Após configurado, use estas ferramentas no seu assistente de IA:

"Search for the latest AI news"
"Extract all links from example.com"
"Crawl the documentation site and summarize it"
"Monitor this page for changes"
"Extract product prices from this e-commerce site"

🔒 Segurança e Privacidade

• Autenticação Segura: Chaves de API exigidas para todas as ferramentas medidas
• Armazenamento Local: Chaves de API armazenadas com segurança em ~/.crawlforge/config.json
• Somente HTTPS: Todas as conexões usam HTTPS criptografado
• Sem Retenção de Dados: Não armazenamos dados extraídos, apenas logs de uso
• Limitação de Taxa: Proteção integrada contra abuso
• Conformidade: Respeita robots.txt e requisitos da GDPR

Segurança e Aprovações

• Imposição de SSRF: Cada URL extraída é validada antes do envio da solicitação — apenas http/https; bloqueia loopback, RFC1918, faixas IPv6 privadas/link-local, endpoints de metadados de nuvem (GCP, Azure) e portas perigosas (SSH, SMTP, DNS, MySQL, Postgres, Redis, MongoDB, etc.). Redirecionamentos são revalidados a cada salto, limitados a 5.
• Proteção de endpoint de backend (v3.0.18): As chamadas do próprio servidor para CrawlForge.dev usam uma lista de permissões separada com falha fechada ({crawlforge.dev, www.crawlforge.dev, api.crawlforge.dev}, HTTPS obrigatório). Definir CRAWLFORGE_API_URL para um host arbitrário é bloqueado no momento da análise.
• Lista de permissões de ações: scrape_with_actions aceita apenas 7 tipos de ação (wait, click, type, press, scroll, screenshot, executeJavaScript). Não existem primitivas de download, escrita de arquivo ou navegação arbitrária entre páginas.
• Portão JavaScript: A ação executeJavaScript lança erro por padrão. Defina ALLOW_JAVASCRIPT_EXECUTION=true no momento da implantação para habilitar (não recomendado em produção).
• Elicitação MCP (v3.6.0): Quatro ferramentas solicitam confirmação do usuário antes de executar operações caras — deep_research (>50 URLs), batch_scrape (modo síncrono, >25 URLs), crawl_deep (projeção >500 páginas), extract_structured (esquema com >3 campos obrigatórios sem LLM configurado). Situações de crédito baixo também eliciam. A confirmação é melhor esforço: se o cliente MCP não suportar elicitação, a ferramenta prossegue (falha aberta).
• Portão de crédito por ferramenta: Cada ferramenta é envolvida com withAuth() e é medida — os créditos são verificados e deduzidos antes da execução, e uma chave de API válida é exigida para cada ferramenta (falha fechada desde v3.0.18).

Consulte docs/sandboxing-and-approvals.md para a referência completa.

Atualizações de Segurança

v3.0.3 (2025-10-01): Removida vulnerabilidade de bypass de autenticação. Todos os usuários devem autenticar com chaves de API válidas.

Para a política de segurança completa e como relatar uma vulnerabilidade, consulte SECURITY.md.

↑ Voltar ao topo

🆘 Suporte

• Documentação: https://www.crawlforge.dev/docs
• Problemas: GitHub Issues
• E-mail: support@crawlforge.dev
• Discord: Junte-se à nossa comunidade

📄 Licença

Licença MIT — consulte o arquivo LICENSE para detalhes.

🤝 Contribuindo

Contribuições são bem-vindas! Leia nosso Guia de Contribuição primeiro.

Feito com ❤️ pela equipe CrawlForge

Website | Documentação | Referência da API