Firecrawl MCP Server

oficial

Extraia dados da web com Firecrawl

Documentação

Servidor MCP Firecrawl

Um servidor Model Context Protocol (MCP) que traz o Firecrawl para agentes de IA compatíveis com MCP — pesquise, extraia e interaja com a web ao vivo para obter contexto limpo e pronto para agentes.

Muito obrigado a @vrknetha, @knacklabs pela implementação inicial!

Funcionalidades

Pesquise na web e obtenha o conteúdo completo da página
Extraia qualquer URL em dados limpos e estruturados
Interaja com páginas — clique, navegue e opere
Pesquisa aprofundada com agente autônomo
Novas tentativas automáticas e limitação de taxa
Suporte à nuvem e auto-hospedagem
Suporte a SSE

Experimente nosso Servidor MCP no playground do MCP.so ou no Klavis AI.

Instalação

Executando com npx

env FIRECRAWL_API_KEY=fc-YOUR_API_KEY npx -y firecrawl-mcp

Instalação Manual

npm install -g firecrawl-mcp

Executando no Cursor

Configurando o Cursor 🖥️ Nota: Requer Cursor versão 0.45.6+ Para obter as instruções de configuração mais atualizadas, consulte a documentação oficial do Cursor sobre configuração de servidores MCP: Guia de Configuração do Servidor MCP no Cursor

Para configurar o Firecrawl MCP no Cursor v0.48.6

Abra as Configurações do Cursor
Vá para Funcionalidades > Servidores MCP
Clique em "+ Adicionar novo servidor MCP global"

Insira o seguinte código:

{
  "mcpServers": {
    "firecrawl-mcp": {
      "command": "npx",
      "args": ["-y", "firecrawl-mcp"],
      "env": {
        "FIRECRAWL_API_KEY": "YOUR-API-KEY"
      }
    }
  }
}

Para configurar o Firecrawl MCP no Cursor v0.45.6

Abra as Configurações do Cursor
Vá para Funcionalidades > Servidores MCP
Clique em "+ Adicionar Novo Servidor MCP"
Insira o seguinte:
- Nome: "firecrawl-mcp" (ou seu nome preferido)
- Tipo: "command"
- Comando: env FIRECRAWL_API_KEY=your-api-key npx -y firecrawl-mcp

Se você estiver usando Windows e estiver enfrentando problemas, tente cmd /c "set FIRECRAWL_API_KEY=your-api-key && npx -y firecrawl-mcp"

Substitua your-api-key pela sua chave de API do Firecrawl. Se você ainda não tem uma, pode criar uma conta e obtê-la em https://www.firecrawl.dev/app/api-keys

Após adicionar, atualize a lista de servidores MCP para ver as novas ferramentas. O Agente Composer usará automaticamente o Firecrawl MCP quando apropriado, mas você pode solicitá-lo explicitamente descrevendo suas necessidades de extração web. Acesse o Composer via Command+L (Mac), selecione "Agent" ao lado do botão enviar e insira sua consulta.

Executando no Windsurf

Adicione isto ao seu ./codeium/windsurf/model_config.json:

{
  "mcpServers": {
    "mcp-server-firecrawl": {
      "command": "npx",
      "args": ["-y", "firecrawl-mcp"],
      "env": {
        "FIRECRAWL_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Executando com Modo Local HTTP Transmissível

Para executar o servidor usando HTTP Transmissível localmente em vez do transporte stdio padrão:

env HTTP_STREAMABLE_SERVER=true FIRECRAWL_API_KEY=fc-YOUR_API_KEY npx -y firecrawl-mcp

Use a url: http://localhost:3000/mcp

Instalando via Smithery (Legado)

Para instalar o Firecrawl para Claude Desktop automaticamente via Smithery:

npx -y @smithery/cli install @mendableai/mcp-server-firecrawl --client claude

Executando no VS Code

Para instalação com um clique, clique em um dos botões de instalação abaixo...

Para instalação manual, adicione o seguinte bloco JSON ao seu arquivo de Configurações do Usuário (JSON) no VS Code. Você pode fazer isso pressionando Ctrl + Shift + P e digitando Preferences: Open User Settings (JSON).

{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "apiKey",
        "description": "Firecrawl API Key",
        "password": true
      }
    ],
    "servers": {
      "firecrawl": {
        "command": "npx",
        "args": ["-y", "firecrawl-mcp"],
        "env": {
          "FIRECRAWL_API_KEY": "${input:apiKey}"
        }
      }
    }
  }
}

Opcionalmente, você pode adicioná-lo a um arquivo chamado .vscode/mcp.json em seu espaço de trabalho. Isso permitirá que você compartilhe a configuração com outras pessoas:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "apiKey",
      "description": "Firecrawl API Key",
      "password": true
    }
  ],
  "servers": {
    "firecrawl": {
      "command": "npx",
      "args": ["-y", "firecrawl-mcp"],
      "env": {
        "FIRECRAWL_API_KEY": "${input:apiKey}"
      }
    }
  }
}

Configuração

Variáveis de Ambiente

Obrigatório para API na Nuvem

FIRECRAWL_API_KEY: Sua chave de API do Firecrawl
- Obrigatório ao usar a API na nuvem (padrão)
- Opcional ao usar instância auto-hospedada com FIRECRAWL_API_URL
FIRECRAWL_API_URL (Opcional): Endpoint de API personalizado para instâncias auto-hospedadas
- Exemplo: https://firecrawl.your-domain.com
- Se não fornecido, a API na nuvem será usada (requer chave de API)

MCP OAuth (Tokens de acesso Bearer)

O Firecrawl hospedado pode emitir tokens de acesso OAuth (fco_…) através do servidor de autorização em firecrawl.dev. Este servidor MCP encaminha a credencial que resolver para a API Firecrawl como Authorization: Bearer ….

Transportes de stream HTTP (CLOUD_SERVICE=true, HTTP_STREAMABLE_SERVER=true ou SSE_LOCAL=true): Os clientes devem enviar Authorization: Bearer <fco_access_token> nas requisições MCP. Um token bearer OAuth tem precedência sobre x-firecrawl-api-key / x-api-key quando ambos estão presentes.
stdio: Use FIRECRAWL_OAUTH_TOKEN para um token de acesso estático ou continue usando FIRECRAWL_API_KEY para uma chave de API.

Use apenas tokens de acesso (fco_…). Tokens de atualização (fcr_…) devem ser trocados no endpoint de token, não passados para a API de extração/pesquisa.

Configuração Opcional

Configuração de Nova Tentativa

FIRECRAWL_RETRY_MAX_ATTEMPTS: Número máximo de tentativas de nova tentativa (padrão: 3)
FIRECRAWL_RETRY_INITIAL_DELAY: Atraso inicial em milissegundos antes da primeira nova tentativa (padrão: 1000)
FIRECRAWL_RETRY_MAX_DELAY: Atraso máximo em milissegundos entre novas tentativas (padrão: 10000)
FIRECRAWL_RETRY_BACKOFF_FACTOR: Multiplicador de backoff exponencial (padrão: 2)

Monitoramento de Uso de Créditos

FIRECRAWL_CREDIT_WARNING_THRESHOLD: Limiar de aviso de uso de créditos (padrão: 1000)
FIRECRAWL_CREDIT_CRITICAL_THRESHOLD: Limiar crítico de uso de créditos (padrão: 100)

Exemplos de Configuração

Para uso da API na nuvem com nova tentativa e monitoramento de créditos personalizados:

# Required for cloud API
export FIRECRAWL_API_KEY=your-api-key

# Optional retry configuration
export FIRECRAWL_RETRY_MAX_ATTEMPTS=5        # Increase max retry attempts
export FIRECRAWL_RETRY_INITIAL_DELAY=2000    # Start with 2s delay
export FIRECRAWL_RETRY_MAX_DELAY=30000       # Maximum 30s delay
export FIRECRAWL_RETRY_BACKOFF_FACTOR=3      # More aggressive backoff

# Optional credit monitoring
export FIRECRAWL_CREDIT_WARNING_THRESHOLD=2000    # Warning at 2000 credits
export FIRECRAWL_CREDIT_CRITICAL_THRESHOLD=500    # Critical at 500 credits

Para instância auto-hospedada:

# Required for self-hosted
export FIRECRAWL_API_URL=https://firecrawl.your-domain.com

# Optional authentication for self-hosted
export FIRECRAWL_API_KEY=your-api-key  # If your instance requires auth

# Custom retry configuration
export FIRECRAWL_RETRY_MAX_ATTEMPTS=10
export FIRECRAWL_RETRY_INITIAL_DELAY=500     # Start with faster retries

Uso com Claude Desktop

Adicione isto ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-server-firecrawl": {
      "command": "npx",
      "args": ["-y", "firecrawl-mcp"],
      "env": {
        "FIRECRAWL_API_KEY": "YOUR_API_KEY_HERE",

        "FIRECRAWL_RETRY_MAX_ATTEMPTS": "5",
        "FIRECRAWL_RETRY_INITIAL_DELAY": "2000",
        "FIRECRAWL_RETRY_MAX_DELAY": "30000",
        "FIRECRAWL_RETRY_BACKOFF_FACTOR": "3",

        "FIRECRAWL_CREDIT_WARNING_THRESHOLD": "2000",
        "FIRECRAWL_CREDIT_CRITICAL_THRESHOLD": "500"
      }
    }
  }
}

Configuração do Sistema

O servidor inclui vários parâmetros configuráveis que podem ser definidos via variáveis de ambiente. Aqui estão os valores padrão se não configurados:

const CONFIG = {
  retry: {
    maxAttempts: 3, // Number of retry attempts for rate-limited requests
    initialDelay: 1000, // Initial delay before first retry (in milliseconds)
    maxDelay: 10000, // Maximum delay between retries (in milliseconds)
    backoffFactor: 2, // Multiplier for exponential backoff
  },
  credit: {
    warningThreshold: 1000, // Warn when credit usage reaches this level
    criticalThreshold: 100, // Critical alert when credit usage reaches this level
  },
};

Essas configurações controlam:

Comportamento de Nova Tentativa
- Tenta novamente automaticamente requisições com falha devido a limites de taxa
- Usa backoff exponencial para evitar sobrecarregar a API
- Exemplo: Com as configurações padrão, novas tentativas serão feitas em:
  - 1ª tentativa: 1 segundo de atraso
  - 2ª tentativa: 2 segundos de atraso
  - 3ª tentativa: 4 segundos de atraso (limitado pelo maxDelay)
Monitoramento de Uso de Créditos
- Rastreia o consumo de créditos da API para uso da API na nuvem
- Fornece avisos nos limiares especificados
- Ajuda a prevenir interrupção inesperada do serviço
- Exemplo: Com as configurações padrão:
  - Aviso em 1000 créditos restantes
  - Alerta crítico em 100 créditos restantes

Limitação de Taxa e Processamento em Lote

O servidor utiliza os recursos integrados de limitação de taxa e processamento em lote do Firecrawl:

Tratamento automático de limite de taxa com backoff exponencial
Processamento paralelo eficiente para operações em lote
Enfileiramento e limitação inteligente de requisições
Novas tentativas automáticas para erros transitórios

Como Escolher uma Ferramenta

Use este guia para selecionar a ferramenta certa para sua tarefa:

Se você sabe a(s) URL(s) exata(s) que deseja:
- Para uma: use scrape (com formato JSON para dados estruturados)
- Para muitas: use batch_scrape
Se você precisa descobrir URLs em um site: use map
Se você quer pesquisar informações na web: use search
Se você precisa de pesquisa complexa em múltiplas fontes desconhecidas: use agent
Se você quer analisar um site inteiro ou seção: use crawl (com limites!)
Se você precisa de automação de navegador interativa (clicar, digitar, navegar): use scrape + interact

Tabela de Referência Rápida

Ferramenta	Melhor para	Retorna
scrape	Conteúdo de página única	JSON (preferencial) ou markdown
interact	Interagir com uma página extraída	Resultado da execução
batch_scrape	Múltiplas URLs conhecidas	JSON (preferencial) ou markdown[]
map	Descobrir URLs em um site	URL[]
crawl	Extração de múltiplas páginas (com limites)	markdown/html[]
search	Pesquisa na web por informações	results[]
agent	Pesquisa complexa de múltiplas fontes	JSON (dados estruturados)

Guia de Seleção de Formato

Ao usar scrape ou batch_scrape, escolha o formato certo:

Formato JSON (recomendado para a maioria dos casos): Use quando precisar de dados específicos de uma página. Defina um esquema com base no que você precisa extrair. Isso mantém as respostas pequenas e evita estouro da janela de contexto.
Formato Markdown (use com moderação): Apenas quando você genuinamente precisa do conteúdo completo da página, como ler um artigo inteiro para sumarização ou analisar a estrutura da página.

Ferramentas Disponíveis

1. Ferramenta Scrape (`firecrawl_scrape`)

Extraia conteúdo de uma única URL com opções avançadas.

Melhor para:

Extração de conteúdo de página única, quando você sabe exatamente qual página contém a informação.

Não recomendado para:

Extrair conteúdo de múltiplas páginas (use batch_scrape para URLs conhecidas, ou map + batch_scrape para descobrir URLs primeiro, ou crawl para conteúdo completo da página)
Quando você não tem certeza de qual página contém a informação (use search)

Erros comuns:

Usar scrape para uma lista de URLs (use batch_scrape em vez disso).
Usar formato markdown por padrão (use formato JSON para extrair apenas o que você precisa).

Escolhendo o formato certo:

Formato JSON (preferencial): Para a maioria dos casos de uso, use o formato JSON com um esquema para extrair apenas os dados específicos necessários. Isso mantém as respostas focadas e evita estouro da janela de contexto.
Formato Markdown: Apenas quando a tarefa genuinamente requer o conteúdo completo da página (ex.: sumarizar um artigo inteiro, analisar a estrutura da página).

Exemplo de Prompt:

"Obtenha os detalhes do produto de https://example.com/product."

Exemplo de Uso (formato JSON - preferencial):

{
  "name": "firecrawl_scrape",
  "arguments": {
    "url": "https://example.com/product",
    "formats": [
      {
        "type": "json",
        "prompt": "Extract the product information",
        "schema": {
          "type": "object",
          "properties": {
            "name": { "type": "string" },
            "price": { "type": "number" },
            "description": { "type": "string" }
          },
          "required": ["name", "price"]
        }
      }
    ]
  }
}

Exemplo de Uso (formato markdown - quando conteúdo completo é necessário):

{
  "name": "firecrawl_scrape",
  "arguments": {
    "url": "https://example.com/article",
    "formats": ["markdown"],
    "onlyMainContent": true
  }
}

Exemplo de Uso (formato branding - extrair identidade da marca):

{
  "name": "firecrawl_scrape",
  "arguments": {
    "url": "https://example.com",
    "formats": ["branding"]
  }
}

Formato Branding: Extrai identidade de marca abrangente (cores, fontes, tipografia, espaçamento, logotipo, componentes de UI) para análise de design ou replicação de estilo. Privacidade: Defina redactPII: true para retornar conteúdo com informações de identificação pessoal redigidas.

Retorna:

Dados estruturados JSON, markdown, perfil de branding ou outros formatos conforme especificado.

2. Ferramenta Batch Scrape (`firecrawl_batch_scrape`)

Extraia múltiplas URLs de forma eficiente com limitação de taxa integrada e processamento paralelo.

Melhor para:

Recuperar conteúdo de múltiplas páginas, quando você sabe exatamente quais páginas extrair.

Não recomendado para:

Descobrir URLs (use map primeiro se você não souber as URLs)
Extrair uma única página (use scrape)

Erros comuns:

Usar batch_scrape com muitas URLs de uma vez (pode atingir limites de taxa ou estouro de tokens)

Exemplo de Prompt:

"Obtenha o conteúdo destes três posts de blog: [url1, url2, url3]."

Exemplo de Uso:

{
  "name": "firecrawl_batch_scrape",
  "arguments": {
    "urls": ["https://example1.com", "https://example2.com"],
    "options": {
      "formats": ["markdown"],
      "onlyMainContent": true
    }
  }
}

Retorna:

A resposta inclui o ID da operação para verificação de status:

{
  "content": [
    {
      "type": "text",
      "text": "Batch operation queued with ID: batch_1. Use firecrawl_check_batch_status to check progress."
    }
  ],
  "isError": false
}

3. Verificar Status do Lote (`firecrawl_check_batch_status`)

Verifique o status de uma operação em lote.

{
  "name": "firecrawl_check_batch_status",
  "arguments": {
    "id": "batch_1"
  }
}

4. Ferramenta Map (`firecrawl_map`)

Mapeie um site para descobrir todas as URLs indexadas no site.

Melhor para:

Descobrir URLs em um site antes de decidir o que extrair
Encontrar seções específicas de um site

Não recomendado para:

Quando você já sabe qual URL específica precisa (use scrape ou batch_scrape)
Quando você precisa do conteúdo das páginas (use scrape após o mapeamento)

Erros comuns:

Usar crawl para descobrir URLs em vez de map

Exemplo de Prompt:

"Liste todas as URLs em example.com."

Exemplo de Uso:

{
  "name": "firecrawl_map",
  "arguments": {
    "url": "https://example.com"
  }
}

Retorna:

Array de URLs encontradas no site

5. Ferramenta Search (`firecrawl_search`)

Pesquise na web e, opcionalmente, extraia conteúdo dos resultados da pesquisa.

Melhor para:

Encontrar informações específicas em vários sites, quando você não sabe qual site tem a informação.
Quando você precisa do conteúdo mais relevante para uma consulta

Não recomendado para:

Quando você já sabe qual site extrair (use scrape)
Quando você precisa de cobertura abrangente de um único site (use map ou crawl)

Erros comuns:

Usar crawl ou map para perguntas abertas (use search em vez disso)

Exemplo de Uso:

{
  "name": "firecrawl_search",
  "arguments": {
    "query": "latest AI research papers 2023",
    "limit": 5,
    "lang": "en",
    "country": "us",
    "scrapeOptions": {
      "formats": ["markdown"],
      "onlyMainContent": true,
      "redactPII": true
    }
  }
}

Retorna:

Array de resultados da pesquisa (com conteúdo extraído opcional), mais um campo id. Passe esse id para firecrawl_search_feedback depois de usar os resultados para reembolsar 1 crédito (a pesquisa custa 2) e melhorar a qualidade da pesquisa.

Exemplo de Prompt:

"Encontre os artigos de pesquisa mais recentes sobre IA publicados em 2023."

5b. Ferramenta de Feedback de Pesquisa (`firecrawl_search_feedback`)

Envia feedback estruturado sobre um resultado anterior de firecrawl_search. O primeiro feedback por ID de pesquisa reembolsa 1 crédito e melhora a qualidade da pesquisa do Firecrawl. Idempotente por ID de pesquisa.

Chame isso após cada pesquisa que você realmente usar (ou que não ajudou). Feedback ruim/parcial com missingContent é tão valioso quanto um bom feedback.

Desativar: defina FIRECRAWL_NO_SEARCH_FEEDBACK=1 (ou FIRECRAWL_DISABLE_SEARCH_FEEDBACK=1) no ambiente ao iniciar o servidor MCP. A ferramenta firecrawl_search_feedback não será registrada, então os agentes não podem chamá-la. Administradores de equipe também podem desabilitar o feedback no lado do servidor; nesse caso, a ferramenta é registrada, mas sempre retorna feedbackErrorCode: "TEAM_OPTED_OUT".

Campo mais importante: missingContent. É um array de partes específicas de conteúdo que o agente esperava encontrar, mas não encontrou. Uma entrada por tópico ausente — elas se agregam entre equipes e nos dizem o que indexar em seguida.

Limite diário de reembolso (por equipe, por dia UTC, padrão 100 créditos). Uma vez que o creditsRefundedToday de uma equipe atinja dailyRefundCap, envios subsequentes ainda registram feedback, mas não reembolsam mais créditos. A resposta define dailyCapReached: true. Os agentes devem parar de chamar esta ferramenta pelo resto do dia UTC quando virem esse sinalizador.

Exemplo de Uso:

{
  "name": "firecrawl_search_feedback",
  "arguments": {
    "searchId": "0193f6c5-1234-7890-abcd-1234567890ab",
    "rating": "good",
    "valuableSources": [
      {
        "url": "https://docs.firecrawl.dev/features/search",
        "reason": "Most up-to-date description of /search."
      }
    ],
    "missingContent": [
      {
        "topic": "Pricing for the search endpoint",
        "description": "No pricing tier table for /search specifically."
      },
      { "topic": "Per-team rate limits" }
    ],
    "querySuggestions": "Boost docs.firecrawl.dev for queries that mention 'firecrawl'"
  }
}

Retorna:

JSON { success, feedbackId, creditsRefunded, alreadySubmitted? }.

5c. Ferramenta de Feedback Genérico (`firecrawl_feedback`)

Envia feedback estruturado para um trabalho de endpoint v2 concluído através de /v2/feedback. Use isso para feedback em nível de endpoint em trabalhos de scrape, parse, map ou search. Para qualidade de resultado de pesquisa especificamente, prefira firecrawl_search_feedback porque inclui orientação específica de pesquisa.

Mantenha o feedback conciso: use códigos de problema, tags, notas curtas, URLs, números de página e pequenos objetos de metadados. Não inclua saídas brutas de scrape/parse.

Desativar: defina FIRECRAWL_NO_ENDPOINT_FEEDBACK=1 (ou FIRECRAWL_DISABLE_ENDPOINT_FEEDBACK=1) no ambiente ao iniciar o servidor MCP. A ferramenta firecrawl_feedback não será registrada, então os agentes não podem chamá-la.

Exemplo de Uso:

{
  "name": "firecrawl_feedback",
  "arguments": {
    "endpoint": "scrape",
    "jobId": "0193f6c5-1234-7890-abcd-1234567890ab",
    "rating": "partial",
    "issues": ["missing_markdown"],
    "tags": ["docs"],
    "note": "The pricing table was missing from the markdown output.",
    "url": "https://example.com/pricing",
    "pageNumbers": [1],
    "metadata": {
      "format": "markdown"
    }
  }
}

Retorna:

JSON { success, feedbackId, creditsRefunded, creditsRefundedToday?, dailyRefundCap?, dailyCapReached?, alreadySubmitted?, warning? }.

6. Ferramenta Crawl (`firecrawl_crawl`)

Inicia um trabalho de rastreamento assíncrono em um site e extrai conteúdo de todas as páginas.

Melhor para:

Extrair conteúdo de múltiplas páginas relacionadas, quando você precisa de cobertura abrangente.

Não recomendado para:

Extrair conteúdo de uma única página (use scrape)
Quando os limites de token são uma preocupação (use map + batch_scrape)
Quando você precisa de resultados rápidos (o rastreamento pode ser lento)

Aviso: As respostas de rastreamento podem ser muito grandes e podem exceder os limites de token. Limite a profundidade do rastreamento e o número de páginas, ou use map + batch_scrape para melhor controle.

Erros comuns:

Definir limit ou maxDepth muito alto (causa estouro de token)
Usar crawl para uma única página (use scrape em vez disso)

Exemplo de Prompt:

"Obtenha todos os posts do blog dos dois primeiros níveis de example.com/blog."

Exemplo de Uso:

{
  "name": "firecrawl_crawl",
  "arguments": {
    "url": "https://example.com/blog/*",
    "maxDepth": 2,
    "limit": 100,
    "allowExternalLinks": false,
    "deduplicateSimilarURLs": true
  }
}

Retorna:

A resposta inclui o ID da operação para verificação de status:

{
  "content": [
    {
      "type": "text",
      "text": "Started crawl for: https://example.com/* with job ID: 550e8400-e29b-41d4-a716-446655440000. Use firecrawl_check_crawl_status to check progress."
    }
  ],
  "isError": false
}

7. Verificar Status do Rastreamento (`firecrawl_check_crawl_status`)

Verifique o status de um trabalho de rastreamento.

{
  "name": "firecrawl_check_crawl_status",
  "arguments": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Retorna:

A resposta inclui o status do trabalho de rastreamento:

8. Ferramenta Extract (`firecrawl_extract`)

Extraia informações estruturadas de páginas da web usando capacidades de LLM. Suporta tanto IA na nuvem quanto extração LLM auto-hospedada.

Melhor para:

Extrair dados estruturados específicos como preços, nomes, detalhes.

Não recomendado para:

Quando você precisa do conteúdo completo de uma página (use scrape)
Quando você não está procurando dados estruturados específicos

Argumentos:

urls: Array de URLs para extrair informações
prompt: Prompt personalizado para a extração LLM
systemPrompt: Prompt do sistema para guiar o LLM
schema: Esquema JSON para extração de dados estruturados
allowExternalLinks: Permitir extração de links externos
enableWebSearch: Habilitar pesquisa na web para contexto adicional
includeSubdomains: Incluir subdomínios na extração

Ao usar uma instância auto-hospedada, a extração usará seu LLM configurado. Para API na nuvem, usa o serviço LLM gerenciado do Firecrawl. Exemplo de Prompt:

"Extraia o nome do produto, preço e descrição destas páginas de produto."

Exemplo de Uso:

{
  "name": "firecrawl_extract",
  "arguments": {
    "urls": ["https://example.com/page1", "https://example.com/page2"],
    "prompt": "Extract product information including name, price, and description",
    "systemPrompt": "You are a helpful assistant that extracts product information",
    "schema": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "price": { "type": "number" },
        "description": { "type": "string" }
      },
      "required": ["name", "price"]
    },
    "allowExternalLinks": false,
    "enableWebSearch": false,
    "includeSubdomains": false
  }
}

Retorna:

Dados estruturados extraídos conforme definido pelo seu esquema

{
  "content": [
    {
      "type": "text",
      "text": {
        "name": "Example Product",
        "price": 99.99,
        "description": "This is an example product description"
      }
    }
  ],
  "isError": false
}

9. Ferramenta Agent (`firecrawl_agent`)

Agente de pesquisa web autônomo. Esta é uma camada de agente de IA separada que navega independentemente na internet, pesquisa informações, navega por páginas e extrai dados estruturados com base em sua consulta.

Como funciona:

O agente realiza pesquisas na web, segue links, lê páginas e coleta dados de forma autônoma. Isso é executado assincronamente - retorna um ID de trabalho imediatamente, e você consulta firecrawl_agent_status para verificar quando estiver concluído e recuperar os resultados.

Fluxo de trabalho assíncrono:

Chame firecrawl_agent com seu prompt/esquema → retorna ID do trabalho
Faça outro trabalho enquanto o agente pesquisa (pode levar minutos para consultas complexas)
Consulte firecrawl_agent_status com o ID do trabalho para verificar o progresso
Quando o status for "completed", a resposta inclui os dados extraídos

Melhor para:

Tarefas de pesquisa complexas onde você não sabe as URLs exatas
Coleta de dados de múltiplas fontes
Encontrar informações espalhadas pela web
Tarefas onde você pode fazer outro trabalho enquanto espera pelos resultados

Não recomendado para:

Extração simples de página única onde você sabe a URL (use scrape com formato JSON - mais rápido e barato)

Argumentos:

prompt: Descrição em linguagem natural dos dados que você deseja (obrigatório, máximo 10.000 caracteres)
urls: Array opcional de URLs para focar o agente em páginas específicas
schema: Esquema JSON opcional para saída estruturada

Exemplo de Prompt:

"Encontre os fundadores do Firecrawl e suas origens"

Exemplo de Uso (iniciar agente, depois consultar resultados):

{
  "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" }
            }
          }
        }
      }
    }
  }
}

Em seguida, consulte com firecrawl_agent_status usando o ID do trabalho retornado.

Exemplo de Uso (com URLs - agente foca em páginas específicas):

{
  "name": "firecrawl_agent",
  "arguments": {
    "urls": ["https://docs.firecrawl.dev", "https://firecrawl.dev/pricing"],
    "prompt": "Compare the features and pricing information from these pages"
  }
}

Retorna:

ID do trabalho para verificação de status. Use firecrawl_agent_status para consultar os resultados.

10. Verificar Status do Agente (`firecrawl_agent_status`)

Verifique o status de um trabalho de agente e recupere os resultados quando concluído. Use isso para consultar os resultados após iniciar um agente.

Padrão de consulta: A pesquisa do agente pode levar minutos para consultas complexas. Consulte este endpoint periodicamente (ex.: a cada 10-30 segundos) até que o status seja "completed" ou "failed".

{
  "name": "firecrawl_agent_status",
  "arguments": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Status possíveis:

processing: O agente ainda está pesquisando - verifique novamente mais tarde
completed: Pesquisa concluída - a resposta inclui os dados extraídos
failed: Ocorreu um erro

11. Ferramentas de Monitoramento (`firecrawl_monitor_*`)

Crie e gerencie monitores de página recorrentes. Os monitores executam extrações ou rastreamentos agendados, comparam cada resultado com o último instantâneo retido e podem notificar por webhook ou e-mail.

Melhor para:

Observar uma página ou algumas páginas ao longo do tempo
Alertar sobre mudanças significativas usando um objetivo em linguagem simples
Rastrear histórico de verificações e diferenças em nível de página

Padrão de criação recomendado:

Use page ou pages mais goal. O servidor MCP constrói a solicitação de monitor com um agendamento de 30 minutos e a API habilita o julgamento de mudança significativa automaticamente.

O julgamento de mudança significativa é executado automaticamente quando goal está definido. Webhooks de página expõem isMeaningful e judgment em eventos monitor.page.

Escreva objetivos como instruções de monitor concisas de 2-3 frases. Diga o que deve acionar um alerta, preserve qualquer escopo que o usuário deu e inclua exclusões específicas de intenção apenas quando óbvias na solicitação. Ruídos genéricos como espaços em branco, alterações apenas de formatação, IDs de solicitação, parâmetros de rastreamento, metadados genéricos e cromo de página não relacionado já são tratados pelo julgador, portanto, não os repita em todos os objetivos. Se o usuário for vago, mantenha o objetivo amplo; se ele pedir monitoramento amplo ou "qualquer mudança", preserve isso. Se o usuário disser que não se importa com algo, inclua isso explicitamente.

{
  "name": "firecrawl_monitor_create",
  "arguments": {
    "page": "https://example.com/pricing",
    "goal": "Alert when pricing, packaging, or launch messaging changes."
  }
}

Múltiplas páginas com webhooks:

{
  "name": "firecrawl_monitor_create",
  "arguments": {
    "pages": ["https://example.com/pricing", "https://example.com/changelog"],
    "goal": "Alert when pricing, packaging, or launch messaging changes.",
    "webhookUrl": "https://example.com/webhooks/firecrawl"
  }
}

Solicitações de criação avançadas:

Passe body quando precisar de alvos de rastreamento, rastreamento de mudanças JSON, retenção personalizada ou controle explícito de judgeEnabled.

{
  "name": "firecrawl_monitor_create",
  "arguments": {
    "body": {
      "name": "Docs monitor",
      "schedule": { "text": "hourly", "timezone": "UTC" },
      "goal": "Alert when docs pages add, remove, or materially change API behavior.",
      "targets": [{ "type": "crawl", "url": "https://example.com/docs" }]
    }
  }
}

Outras ferramentas de monitor:

firecrawl_monitor_list: listar monitores.
firecrawl_monitor_get: obter um monitor.
firecrawl_monitor_update: atualizar campos incluindo goal, judgeEnabled, webhook e notification.
firecrawl_monitor_run: acionar uma verificação agora.
firecrawl_monitor_checks: listar verificações, opcionalmente filtradas por status.
firecrawl_monitor_check: obter resultados em nível de página, incluindo diff, snapshot, judgment.meaningful e judgment.meaningfulChanges.

Sistema de Logging

O servidor inclui logging abrangente:

Status e progresso da operação
Métricas de desempenho
Monitoramento de uso de créditos
Rastreamento de limite de taxa
Condições de erro

Exemplo de mensagens de log:

[INFO] Firecrawl MCP Server initialized successfully
[INFO] Starting scrape for URL: https://example.com
[INFO] Batch operation queued with ID: batch_1
[WARNING] Credit usage has reached warning threshold
[ERROR] Rate limit exceeded, retrying in 2s...

Tratamento de Erros

O servidor fornece tratamento robusto de erros:

Novas tentativas automáticas para erros transitórios
Tratamento de limite de taxa com backoff
Mensagens de erro detalhadas
Avisos de uso de créditos
Resiliência de rede

Exemplo de resposta de erro:

{
  "content": [
    {
      "type": "text",
      "text": "Error: Rate limit exceeded. Retrying in 2 seconds..."
    }
  ],
  "isError": true
}

Desenvolvimento

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

Contribuindo

Faça um fork do repositório
Crie seu branch de funcionalidade
Execute os testes: npm test
Envie um pull request

Agradecimentos aos contribuidores

Obrigado a @vrknetha, @cawstudios pela implementação inicial!

Obrigado ao MCP.so e Klavis AI pela hospedagem e a @gstarwd, @xiangkaiz e @zihaolin96 por integrarem nosso servidor.

Licença

Licença MIT - veja o arquivo LICENSE para detalhes

Firecrawl MCP Server

Documentação

Servidor MCP Firecrawl

Funcionalidades

Instalação

Executando com npx

Instalação Manual

Executando no Cursor

Executando no Windsurf

Executando com Modo Local HTTP Transmissível

Instalando via Smithery (Legado)

Executando no VS Code

Configuração

Variáveis de Ambiente

Obrigatório para API na Nuvem

MCP OAuth (Tokens de acesso Bearer)

Configuração Opcional

Configuração de Nova Tentativa

Monitoramento de Uso de Créditos

Exemplos de Configuração

Uso com Claude Desktop

Configuração do Sistema

Limitação de Taxa e Processamento em Lote

Como Escolher uma Ferramenta

Tabela de Referência Rápida

Guia de Seleção de Formato

Ferramentas Disponíveis

1. Ferramenta Scrape (firecrawl_scrape)

2. Ferramenta Batch Scrape (firecrawl_batch_scrape)

3. Verificar Status do Lote (firecrawl_check_batch_status)

4. Ferramenta Map (firecrawl_map)

5. Ferramenta Search (firecrawl_search)

5b. Ferramenta de Feedback de Pesquisa (firecrawl_search_feedback)

5c. Ferramenta de Feedback Genérico (firecrawl_feedback)

6. Ferramenta Crawl (firecrawl_crawl)

7. Verificar Status do Rastreamento (firecrawl_check_crawl_status)

8. Ferramenta Extract (firecrawl_extract)

9. Ferramenta Agent (firecrawl_agent)

10. Verificar Status do Agente (firecrawl_agent_status)

11. Ferramentas de Monitoramento (firecrawl_monitor_*)

Sistema de Logging

Tratamento de Erros

Desenvolvimento

Contribuindo

Agradecimentos aos contribuidores

Licença

1. Ferramenta Scrape (`firecrawl_scrape`)

2. Ferramenta Batch Scrape (`firecrawl_batch_scrape`)

3. Verificar Status do Lote (`firecrawl_check_batch_status`)

4. Ferramenta Map (`firecrawl_map`)

5. Ferramenta Search (`firecrawl_search`)

5b. Ferramenta de Feedback de Pesquisa (`firecrawl_search_feedback`)

5c. Ferramenta de Feedback Genérico (`firecrawl_feedback`)

6. Ferramenta Crawl (`firecrawl_crawl`)

7. Verificar Status do Rastreamento (`firecrawl_check_crawl_status`)

8. Ferramenta Extract (`firecrawl_extract`)

9. Ferramenta Agent (`firecrawl_agent`)

10. Verificar Status do Agente (`firecrawl_agent_status`)

11. Ferramentas de Monitoramento (`firecrawl_monitor_*`)