ComposioHQ/Firecrawl-Automation

Automação Firecrawl

Execute operações de web crawling e extração do Firecrawl diretamente do Claude Code. Raspe páginas individuais, faça crawling de sites inteiros, extraia dados estruturados com IA, processe listas de URLs em lote e mapeie estruturas de sites sem sair do terminal.

Documentação do toolkit: composio.dev/toolkits/firecrawl

---

Configuração

1. Adicione o servidor MCP do Composio à sua configuração:

   https://rube.app/mcp
   

2. Conecte sua conta do Firecrawl quando solicitado. O agente fornecerá um link de autenticação.
3. Esteja ciente do consumo de créditos — limite seus crawls e teste em conjuntos pequenos de URLs antes de escalar.

---

Fluxos de Trabalho Principais

1. Raspar uma Única Página

Obtenha o conteúdo de uma URL em múltiplos formatos, com ações opcionais no navegador para páginas dinâmicas.

Ferramenta: FIRECRAWL_SCRAPE

Parâmetros principais:

• url (obrigatório) — URL completa para raspar
• formats — formatos de saída: markdown (padrão), html, rawHtml, links, screenshot, json
• onlyMainContent (padrão true) — extrair apenas o conteúdo principal, excluindo navegação/rodapé/anúncios
• waitFor — milissegundos para aguardar a renderização JS (padrão 0)
• timeout — tempo máximo de espera em ms (padrão 30000)
• actions — ações no navegador antes de raspar (clicar, escrever, esperar, pressionar, rolar)
• includeTags / excludeTags — filtrar por tags HTML
• jsonOptions — para extração estruturada com schema e/ou prompt

Exemplo de prompt: "Raspe o conteúdo principal de https://exemplo.com/precos como markdown"

---

2. Fazer Crawling de um Site Inteiro

Descubra e raspe múltiplas páginas de um site com profundidade, filtros de caminho e concorrência configuráveis.

Ferramenta: FIRECRAWL_CRAWL_V2

Parâmetros principais:

• url (obrigatório) — URL inicial para o crawling
• limit (padrão 10) — máximo de páginas a raspar
• maxDiscoveryDepth — limite de profundidade a partir da página raiz
• includePaths / excludePaths — padrões regex para caminhos de URL
• allowSubdomains — incluir subdomínios (padrão false)
• crawlEntireDomain — seguir links irmãos/pais, não apenas filhos (padrão false)
• sitemap — include (padrão), skip ou only
• prompt — linguagem natural para configurar automaticamente as opções do crawler
• scrapeOptions_formats — formato de saída para cada página
• scrapeOptions_onlyMainContent — extração de conteúdo principal por página

Exemplo de prompt: "Faça crawling da seção de docs do firecrawl.dev, máximo 50 páginas, apenas caminhos que correspondam a docs"

---

3. Extrair Dados Estruturados

Extraia dados JSON estruturados de páginas web usando IA com um prompt em linguagem natural ou schema JSON.

Ferramenta: FIRECRAWL_EXTRACT

Parâmetros principais:

• urls (obrigatório) — array de URLs para extrair (máx. 10 em beta). Suporta curingas como https://exemplo.com/blog/*
• prompt — descrição em linguagem natural do que extrair
• schema — JSON Schema definindo a estrutura de saída desejada
• enable_web_search — permitir crawling de links fora dos domínios iniciais (padrão false)

Pelo menos um dos parâmetros prompt ou schema deve ser fornecido.

Verifique o status da extração com FIRECRAWL_EXTRACT_GET usando o id do trabalho retornado.

Exemplo de prompt: "Extraia nome da empresa, níveis de preço e listas de recursos de https://exemplo.com/precos"

---

4. Raspar Múltiplas URLs em Lote

Raspe muitas URLs concorrentemente com configuração compartilhada para coleta eficiente de dados em massa.

Ferramenta: FIRECRAWL_BATCH_SCRAPE

Parâmetros principais:

• urls (obrigatório) — array de URLs para raspar
• formats — formato de saída para todas as páginas (padrão markdown)
• onlyMainContent (padrão true) — extração de conteúdo principal
• maxConcurrency — limite de raspagem paralela
• ignoreInvalidURLs (padrão true) — pular URLs inválidas em vez de falhar o lote
• location — configurações de geolocalização com código do country
• actions — ações no navegador aplicadas a cada página
• blockAds (padrão true) — bloquear anúncios

Exemplo de prompt: "Raspe em lote estas 20 URLs de páginas de produto como markdown com bloqueio de anúncios"

---

5. Mapear Estrutura do Site

Descubra todas as URLs de um site a partir de uma URL inicial, útil para planejar crawls ou auditar a estrutura do site.

Ferramenta: FIRECRAWL_MAP_MULTIPLE_URLS_BASED_ON_OPTIONS

Parâmetros principais:

• url (obrigatório) — URL inicial (deve ser https:// ou http://)
• search — guiar a descoberta de URLs para tipos específicos de página
• limit (padrão 5000, máximo 100000) — máximo de URLs a retornar
• includeSubdomains (padrão true) — incluir subdomínios
• ignoreQueryParameters (padrão true) — deduplicar URLs que diferem apenas por parâmetros de consulta
• sitemap — include, skip ou only

Exemplo de prompt: "Mapeie todas as URLs em docs.exemplo.com, focando em páginas de referência da API"

---

6. Monitorar e Gerenciar Trabalhos de Crawling

Acompanhe o progresso do crawling, recupere resultados e cancele trabalhos problemáticos.

Ferramentas: FIRECRAWL_CRAWL_GET, FIRECRAWL_GET_THE_STATUS_OF_A_CRAWL_JOB, FIRECRAWL_CANCEL_A_CRAWL_JOB

• FIRECRAWL_CRAWL_GET — obter status, progresso, créditos usados e dados das páginas raspadas
• FIRECRAWL_CANCEL_A_CRAWL_JOB — interromper um crawling ativo ou na fila

Ambas requerem o id do trabalho de crawling (UUID) retornado quando o crawling foi iniciado.

Exemplo de prompt: "Verifique o status do trabalho de crawling 019b0806-b7a1-7652-94c1-e865b5d2e89a"

---

Armadilhas Conhecidas

• Limitação de taxa: Firecrawl pode disparar erros "Rate limit exceeded" (429). Prefira FIRECRAWL_BATCH_SCRAPE em vez de muitas chamadas individuais de FIRECRAWL_SCRAPE, e implemente backoff em respostas 429/5xx.
• Consumo de créditos: FIRECRAWL_EXTRACT pode falhar com "Insufficient credits." Limite bem e evite URLs amplas de homepage que geram campos esparsos. Teste em conjuntos pequenos de URLs primeiro.
• Respostas de erro aninhadas: Falhas por página podem estar aninhadas em response.data.code (ex.: SCRAPE_DNS_RESOLUTION_ERROR) mesmo quando a chamada externa da API é bem-sucedida. Sempre valide os campos internos de status/erro.
• Páginas com muito JS: Requisições sem renderização podem perder conteúdo importante. Use waitFor (ex.: 1000-5000ms) para páginas dinâmicas, ou configure scrapeOptions_actions para interagir com a página antes de raspar.
• Precisão do schema de extração: Schemas ou prompts vagos/mutáveis produzem resultados ruidosos e inconsistentes. Congele seu schema e teste em uma amostra pequena antes de escalar para muitas URLs.
• Trabalhos de crawling são assíncronos: FIRECRAWL_CRAWL_V2 retorna imediatamente com um ID de trabalho. Use FIRECRAWL_CRAWL_GET para consultar os resultados. Cancele crawls travados com FIRECRAWL_CANCEL_A_CRAWL_JOB para evitar desperdício de créditos.
• Polling de extração: FIRECRAWL_EXTRACT também é assíncrono para trabalhos maiores. Recupere a saída final com FIRECRAWL_EXTRACT_GET.
• Agrupamento de URLs para extração: Mantenha lotes de URLs de extração pequenos (~10 URLs) para evitar erros de limite de taxa 429.
• Respostas profundamente aninhadas: Os resultados geralmente estão aninhados sob data.data ou mais profundamente. Inspecione a forma retornada em vez de assumir chaves simples.

---

Referência Rápida

Slug da Ferramenta	Descrição
FIRECRAWL_SCRAPE	Raspar uma única URL com opções de formato/ação
FIRECRAWL_CRAWL_V2	Fazer crawling de um site com controle de profundidade/caminho
FIRECRAWL_EXTRACT	Extrair dados estruturados com prompt/schema de IA
FIRECRAWL_BATCH_SCRAPE	Raspar múltiplas URLs em lote concorrentemente
FIRECRAWL_MAP_MULTIPLE_URLS_BASED_ON_OPTIONS	Descobrir/mapear todas as URLs de um site
FIRECRAWL_CRAWL_GET	Obter status e resultados de um trabalho de crawling
FIRECRAWL_GET_THE_STATUS_OF_A_CRAWL_JOB	Verificar progresso de um trabalho de crawling
FIRECRAWL_CANCEL_A_CRAWL_JOB	Cancelar um trabalho de crawling ativo
FIRECRAWL_EXTRACT_GET	Obter status e resultados de um trabalho de extração
FIRECRAWL_CRAWL_PARAMS_PREVIEW	Visualizar parâmetros de crawling antes de iniciar
FIRECRAWL_SEARCH	Pesquisa na web + raspagem dos principais resultados

---

Desenvolvido por Composio