> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firecrawl.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Ferramentas e operações do Firecrawl MCP
> Ferramentas disponíveis, comportamento operacional e tratamento de erros do Firecrawl MCP.
## Ferramentas disponíveis
### 1. Ferramenta de Scraping (`firecrawl_scrape`)
Extraia conteúdo de uma única URL com opções avançadas.
```json theme={null}
{
"name": "firecrawl_scrape",
"arguments": {
"url": "https://example.com",
"formats": ["markdown"],
"onlyMainContent": true,
"waitFor": 1000,
"mobile": false,
"includeTags": ["article", "main"],
"excludeTags": ["nav", "footer"],
"skipTlsVerification": false
}
}
```
Para redigir informações de identificação pessoal, inclua `redactPII` nos argumentos da ferramenta de scraping.
```json theme={null}
{
"name": "firecrawl_scrape",
"arguments": {
"url": "https://example.com/contact",
"formats": ["markdown"],
"redactPII": true
}
}
```
### 2. Ferramenta Map (`firecrawl_map`)
Mapeie um site para descobrir todas as URLs indexadas.
```json theme={null}
{
"name": "firecrawl_map",
"arguments": {
"url": "https://example.com",
"search": "blog",
"sitemap": "include",
"includeSubdomains": false,
"limit": 100,
"ignoreQueryParameters": true
}
}
```
#### Opções da ferramenta Map:
* `url`: URL base do site a ser mapeado
* `search`: Termo de busca opcional para filtrar URLs
* `sitemap`: Controla o uso do sitemap - "include", "skip" ou "only"
* `includeSubdomains`: Indica se os subdomínios devem ser incluídos no mapeamento
* `limit`: Número máximo de URLs a retornar
* `ignoreQueryParameters`: Indica se os parâmetros de consulta devem ser ignorados durante o mapeamento
**Ideal para:** Descobrir URLs em um site antes de decidir quais extrair; encontrar seções específicas de um site.
**Retorna:** Array de URLs encontradas no site.
### 3. Ferramenta de Busca (`firecrawl_search`)
Faça uma busca na web e, opcionalmente, extraia conteúdo dos resultados de busca.
```json theme={null}
{
"name": "firecrawl_search",
"arguments": {
"query": "your search query",
"limit": 5,
"location": "United States",
"tbs": "qdr:m",
"scrapeOptions": {
"formats": ["markdown"],
"onlyMainContent": true
}
}
}
```
#### Opções da ferramenta de busca:
* `query`: String da consulta de busca (obrigatória)
* `limit`: Número máximo de resultados a retornar
* `location`: Localização geográfica dos resultados de busca
* `tbs`: Filtro de busca por período (por exemplo, `qdr:d` para o último dia, `qdr:w` para a última semana, `qdr:m` para o último mês)
* `filter`: Filtro de busca adicional
* `sources`: Array de tipos de fonte a serem pesquisados (`web`, `images`, `news`)
* `scrapeOptions`: Opções de scraping das páginas de resultados de busca
* `enterprise`: Array de opções empresariais (`default`, `anon`, `zdr`)
### 4. Ferramenta Parse (`firecrawl_parse`)
Converta arquivos locais, como documentos PDF, DOCX, XLSX ou HTML, em dados limpos e prontos para LLMs.
```json theme={null}
{
"name": "firecrawl_parse",
"arguments": {
"filePath": "/absolute/path/to/report.pdf",
"formats": ["markdown"]
}
}
```
Quando você executa o Firecrawl MCP localmente em uma instância da API Firecrawl usando `FIRECRAWL_API_URL`, o servidor MCP pode ler `filePath` diretamente e envia os bytes do arquivo para `/v2/parse`.
Quando você usa o servidor MCP hospedado remoto, ele não pode ler arquivos da sua máquina. Nesse caso, `firecrawl_parse` usa uma transferência em duas etapas que também funciona na URL remota sem chave:
1. Chame `firecrawl_parse` com `filePath`. A ferramenta retorna um comando de upload pré-preenchido e um `nextToolCall` contendo um `uploadRef`.
2. Execute o comando de upload na máquina que pode ler o arquivo e chame `firecrawl_parse` novamente com o `uploadRef` retornado.
O comando de upload envia os bytes do arquivo para um destino de upload assinado e temporário. Ele não inclui sua chave de API do Firecrawl.
#### Opções da ferramenta Parse:
* `filePath`: Caminho local do arquivo que você deseja analisar. Use-o na primeira chamada.
* `uploadRef`: Referência retornada pela primeira chamada ao MCP hospedado. Use-a na segunda chamada após o upload ser concluído.
* `formats`: Formatos de resultado. O padrão é `markdown`.
* `parsers`: Controles do analisador, como opções de análise de PDF.
* `contentType`: Substituição opcional do tipo MIME do arquivo.
* `declaredSizeBytes`: Indicação opcional do tamanho do arquivo. O tamanho máximo dos arquivos é 50 MB.
**Ideal para:** Documentos locais ou não públicos que não estão disponíveis em uma URL pública.
**Não recomendado para:** URLs de documentos públicos. Use `firecrawl_scrape`; ele detectará e analisará documentos a partir de URLs.
### 5. Ferramenta de rastreamento (`firecrawl_crawl`)
Inicie um rastreamento assíncrono com opções avançadas.
```json theme={null}
{
"name": "firecrawl_crawl",
"arguments": {
"url": "https://example.com",
"maxDiscoveryDepth": 2,
"limit": 100,
"allowExternalLinks": false,
"deduplicateSimilarURLs": true
}
}
```
### 6. Verificar o status do rastreamento (`firecrawl_check_crawl_status`)
Verifique o status de um job de rastreamento.
```json theme={null}
{
"name": "firecrawl_check_crawl_status",
"arguments": {
"id": "550e8400-e29b-41d4-a716-446655440000"
}
}
```
**Retorna:** O status e o progresso do job de rastreamento, incluindo os resultados, se disponíveis.
Extraia informações estruturadas de páginas da web usando recursos de LLM. Compatível com extração por IA na nuvem e com LLMs auto-hospedados.
```json theme={null}
{
"name": "firecrawl_extract",
"arguments": {
"urls": ["https://example.com/page1", "https://example.com/page2"],
"prompt": "Extract product information including name, price, and description",
"schema": {
"type": "object",
"properties": {
"name": { "type": "string" },
"price": { "type": "number" },
"description": { "type": "string" }
},
"required": ["name", "price"]
},
"allowExternalLinks": false,
"enableWebSearch": false,
"includeSubdomains": false
}
}
```
Resposta de exemplo:
```json theme={null}
{
"content": [
{
"type": "text",
"text": {
"name": "Example Product",
"price": 99.99,
"description": "This is an example product description"
}
}
],
"isError": false
}
```
* `urls`: Array de URLs para extrair informações
* `prompt`: Prompt personalizado para extração com LLM
* `schema`: Schema JSON para extração de dados estruturados
* `allowExternalLinks`: Permitir extração de links externos
* `enableWebSearch`: Habilitar a busca na web para contexto adicional
* `includeSubdomains`: Incluir subdomínios na extração
Ao usar uma instância auto-hospedada, a extração usará o LLM configurado. Na API em nuvem, ela usa o serviço de LLM gerenciado da Firecrawl.
### 8. Ferramenta de Agente (`firecrawl_agent`)
Agente autônomo de pesquisa na web que navega pela internet de forma independente, busca informações, percorre páginas e extrai dados estruturados com base na sua consulta. É executado de forma assíncrona -- retorna imediatamente um ID do job, e você consulta `firecrawl_agent_status` para verificar quando é concluído e recuperar os resultados.
```json theme={null}
{
"name": "firecrawl_agent",
"arguments": {
"prompt": "Find the top 5 AI startups founded in 2024 and their funding amounts",
"schema": {
"type": "object",
"properties": {
"startups": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": { "type": "string" },
"funding": { "type": "string" },
"founded": { "type": "string" }
}
}
}
}
}
}
}
```
Você também pode fornecer URLs específicas para o agente se concentrar:
```json theme={null}
{
"name": "firecrawl_agent",
"arguments": {
"urls": ["https://docs.firecrawl.dev", "https://firecrawl.dev/pricing"],
"prompt": "Compare the features and pricing information from these pages"
}
}
```
#### Opções da ferramenta de agente:
* `prompt`: Descrição em linguagem natural dos dados desejados (obrigatório, máximo de 10.000 caracteres)
* `urls`: Array opcional de URLs para direcionar o agente a páginas específicas
* `schema`: Schema JSON opcional para resultado estruturado
**Ideal para:** Tarefas de pesquisa complexas em que você não conhece as URLs exatas; coleta de dados de várias fontes; encontrar informações dispersas pela web; extração de dados de SPAs com muito JavaScript que falham com o scraping comum.
**Retorna:** ID do job para verificar o status. Use `firecrawl_agent_status` para consultar os resultados.
### 9. Verificar o status do agente (`firecrawl_agent_status`)
Verifique o status de um job de agente e recupere os resultados quando ele for concluído. Consulte a cada 15–30 segundos e continue consultando por pelo menos 2–3 minutos antes de considerar que a solicitação falhou.
```json theme={null}
{
"name": "firecrawl_agent_status",
"arguments": {
"id": "550e8400-e29b-41d4-a716-446655440000"
}
}
```
#### Opções de status do agente:
* `id`: O ID do job do agente retornado por `firecrawl_agent` (obrigatório)
**Status possíveis:**
* `processing`: O agente ainda está pesquisando -- continue consultando
* `completed`: Pesquisa concluída -- a resposta inclui os dados extraídos
* `failed`: Ocorreu um erro
**Retorna:** Status, progresso e resultados (se concluído) do job do agente.
### 10. Interaja com uma página (`firecrawl_interact`)
Interaja com uma página em uma sessão ativa do navegador: clique em botões, preencha formulários, extraia conteúdo dinâmico ou navegue para outras páginas.
Use um destes dois modos de direcionamento:
* Passe `url` para abrir e interagir com uma nova página em uma única chamada MCP.
* Passe o `scrapeId` de uma chamada anterior para `firecrawl_scrape` para reutilizar a página já carregada.
Não passe `url` e `scrapeId` ao mesmo tempo. Forneça `prompt` ou `code`. `scrapeOptions` só pode ser usado no modo `url`.
**Exemplo do modo URL:**
```json theme={null}
{
"name": "firecrawl_interact",
"arguments": {
"url": "https://example.com/products",
"prompt": "Click on the first product and tell me its price"
}
}
```
**Exemplo de reutilização de scraping:**
```json theme={null}
{
"name": "firecrawl_interact",
"arguments": {
"scrapeId": "scrape-id-from-previous-scrape",
"prompt": "Click the Sign In button"
}
}
```
#### Opções da ferramenta Interact:
* `url`: Página com a qual interagir; abre a sessão para você. Use esta ou `scrapeId`.
* `scrapeId`: ID do job de scraping de uma chamada anterior a `firecrawl_scrape`. Use este ou `url`.
* `prompt`: Instrução em linguagem natural que descreve a ação a ser realizada. Forneça `prompt` ou `code`.
* `code`: Código a ser executado na sessão do navegador. Forneça `code` ou `prompt`.
* `language`: `bash`, `python` ou `node` (opcional; o padrão é `node`; usado apenas com `code`).
* `timeout`: Tempo limite de execução em segundos, de 1 a 300 (opcional; o padrão é 30).
* `scrapeOptions`: Controles opcionais de scraping usados apenas no modo `url`.
**Ideal para:** Fluxos de trabalho de várias etapas em uma única página — pesquisar em um site, clicar nos resultados, preencher formulários e extrair dados que exigem interação.
**Retorna:** Resultado da interação, incluindo URLs do resultado e da visualização em tempo real.
### 11. Encerrar sessão de interação (`firecrawl_interact_stop`)
Encerre uma sessão de interação de uma página extraída. Chame esta ferramenta ao terminar de interagir para liberar recursos.
```json theme={null}
{
"name": "firecrawl_interact_stop",
"arguments": {
"scrapeId": "scrape-id-from-previous-scrape"
}
}
```
#### Opções para interromper o Interact:
* `scrapeId`: O ID de scraping da sessão a ser interrompida (obrigatório)
**Retorna:** Confirmação de que a sessão foi interrompida.
## Sistema de logs
O servidor inclui logs detalhados:
* Status e progresso das operações
* Métricas de desempenho
* Monitoramento do uso de créditos
* Acompanhamento dos limites de taxa
* Condições de erro
Exemplos de mensagens de log:
```
[INFO] Firecrawl MCP Server initialized successfully
[INFO] Starting scrape for URL: https://example.com
[INFO] Starting crawl for URL: https://example.com
[WARNING] Credit usage has reached warning threshold
[ERROR] Rate limit exceeded, retrying in 2s...
```
## Tratamento de erros
O servidor oferece tratamento robusto de erros:
* Novas tentativas automáticas para erros transitórios
* Tratamento de limite de taxa com backoff
* Mensagens de erro detalhadas
* Avisos sobre o uso de créditos
* Resiliência de rede
Exemplo de resposta de erro:
```json theme={null}
{
"content": [
{
"type": "text",
"text": "Error: Rate limit exceeded. Retrying in 2 seconds..."
}
],
"isError": true
}
```