Firecrawl

Firecrawl MCP Server

Um servidor Model Context Protocol (MCP) que traz 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.

Agradecimentos especiais a @vrknetha, @knacklabs pela implementação inicial!

Recursos

• Pesquise na web e obtenha o conteúdo completo da página
• Pesquise em um índice criado para agentes de codificação: issues do GitHub, pull requests mesclados, READMEs e documentação
• Extraia qualquer URL em dados limpos e estruturados
• Interaja com páginas — clique, navegue e opere
• Pesquisa aprofundada com agente autônomo
• Tentativas automáticas e limitação de taxa
• Suporte a nuvem e auto-hospedagem
• Suporte a SSE

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

Instalação

MCP hospedado (camada gratuita sem chave)

Conecte-se ao servidor remoto hospedado sem configuração:

https://mcp.firecrawl.dev/v2/mcp

Na camada gratuita sem chave, scrape, search e parse funcionam sem chave de API (com limite de taxa). Outras ferramentas como crawl, map e agent ainda precisam de uma chave.

Prefira OAuth ou uma chave de API sempre que o usuário puder se cadastrar. Isso desbloqueia o conjunto completo de ferramentas e limites mais altos.

Para uma conexão interativa de conta, configure seu cliente MCP para usar esta URL de servidor. Este é um endpoint MCP, não uma página de navegador; use o fluxo de conexão de conta do cliente e não adicione uma segunda entrada de servidor Firecrawl ao reconectar:

https://mcp.firecrawl.dev/v2/mcp-oauth

Para uma conexão com chave de API (por exemplo, uma integração não supervisionada), mantenha a URL do servidor como:

https://mcp.firecrawl.dev/v2/mcp

Em seguida, configure o cabeçalho seguro ou a configuração de segredo do cliente com:

Authorization: Bearer <FIRECRAWL_API_KEY>

Nunca coloque uma chave de API na URL do servidor. Nunca coloque uma chave de API em um chat de agente. Configure-a diretamente no cliente ou no gerenciador de segredos. Consulte o guia de configuração do MCP hospedado e o guia de integração de agentes para instruções específicas do cliente.

Endpoint somente de pesquisa

Uma superfície somente leitura e somente pesquisa também está hospedada em:

https://mcp.firecrawl.dev/v2/mcp-search

Ela expõe um conjunto fixo de seis ferramentas somente leitura: firecrawl_search e as cinco ferramentas firecrawl_research_*. Ela não realiza busca de conteúdo de páginas e tem sua própria identidade OAuth; o endpoint completo acima permanece inalterado. Consulte docs/search-profile.md para o contrato completo.

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 a versão 0.45.6+ do Cursor Para instruções de configuração mais atualizadas, consulte a documentação oficial do Cursor sobre configuração de servidores MCP: Guia de Configuração de Servidores MCP do Cursor

Para configurar o Firecrawl MCP no Cursor v0.48.6

1. Abra as Configurações do Cursor
2. Vá para Recursos > Servidores MCP
3. Clique em "+ Adicionar novo servidor MCP global"
4. 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

1. Abra as Configurações do Cursor
2. Vá para Recursos > Servidores MCP
3. Clique em "+ Adicionar Novo Servidor MCP"
4. Insira o seguinte:
   • Nome: "firecrawl-mcp" (ou o nome de sua preferência)
   • Tipo: "comando"
   • 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 tiver 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 Composer Agent usará automaticamente o Firecrawl MCP quando apropriado, mas você pode solicitá-lo explicitamente descrevendo suas necessidades de extração da web. Acesse o Composer via Command+L (Mac), selecione "Agent" ao lado do botão de envio 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 Streamable HTTP em Modo Local

Para executar o servidor usando Streamable HTTP 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 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 no seu workspace. 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

Necessárias para a API em Nuvem

• FIRECRAWL_API_KEY: Sua chave de API do Firecrawl
  • Necessária ao usar a API em 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 for fornecido, a API em 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 do 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 solicitaçõ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_…). Os tokens de atualização (fcr_…) devem ser trocados no endpoint de token, não passados para a API de extração/pesquisa.

Superfície somente de pesquisa (hospedada)

No modo hospedado (CLOUD_SERVICE=true), uma segunda instância no mesmo processo atende ao endpoint somente de pesquisa. O serviço incluído tem um contrato de implantação fixo: o nginx roteia /v2/mcp-search para a instância na porta local 3001, e o identificador de recurso protegido por OAuth é https://mcp.firecrawl.dev/v2/mcp-search.

FIRECRAWL_MCP_SEARCH_ENABLED (padrão true) é a alternância operacional suportada; defina-a como false para impedir que a instância de pesquisa inicie. O processo Node também aceita FIRECRAWL_MCP_SEARCH_PORT, FIRECRAWL_MCP_SEARCH_ENDPOINT e FIRECRAWL_MCP_SEARCH_RESOURCE_URL para testes isolados. Essas substituições não reconfiguram as rotas nginx incluídas nem a lista de permissões do servidor de autorização e não devem ser usadas de forma independente na implantação hospedada.

A instância de pesquisa exige autenticação para cada solicitação (incluindo tools/list) e rejeita tokens OAuth cujo público não corresponda ao seu próprio recurso.

Exemplos de Configuração

Para uso da API em nuvem:

export FIRECRAWL_API_KEY=your-api-key

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

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

Como Escolher uma Ferramenta

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

• Se você sabe a URL exata que deseja: use scrape (com formato JSON para dados estruturados)
• Se você tem várias URLs conhecidas: chame scrape para cada URL. Se você precisar especificamente de uma operação de API em lote, use o endpoint de lote da API Firecrawl fora do MCP.
• Se você precisa descobrir URLs em um site: use map
• Se você deseja pesquisar na web por informações: use search
• Se você tem uma pergunta de programação (uma biblioteca, um contrato de API, uma mensagem de erro, um bug conhecido): use developer search
• Se você precisa de artigos científicos (literatura biomédica, ciências da vida, clínica ou arXiv): use research tools — elas pesquisam resumos e texto completo de artigos. search com categories: ["research"] é uma coisa diferente: um filtro de site sobre resultados web comuns.
• Se você precisa de pesquisa complexa em múltiplas fontes desconhecidas: use agent
• Se você deseja analisar um site inteiro ou uma seção: use crawl (com limites!)
• Se você precisa de automação interativa de navegador (clicar, digitar, navegar): use interact com uma URL para uma página nova, ou scrape + interact quando você já extraiu a página ou precisa de controle mais preciso de extração

Tabela de Referência Rápida

Ferramenta	Melhor para	Retorna
scrape	Conteúdo de página única	JSON (preferido) ou markdown
interact	Interagir com uma URL ou página extraída	Resultado da execução + scrapeId para modo URL
map	Descobrir URLs em um site	URL[]
crawl	Extração de múltiplas páginas (com limites)	status/dados finais do crawl após polling interno
parse	Arquivos e referências de upload hospedadas	markdown, JSON ou saída de documento
search	Pesquisa web por informações	results[]
developer	Perguntas de programação sobre fontes de desenvolvedores	results[] com passagens
agent	Pesquisa complexa de múltiplas fontes	JSON (dados estruturados)
monitor	Verificações recorrentes de páginas	metadados e diffs de monitor/check
research	Pesquisa de artigos e repositórios GitHub	resultados de pesquisa e correspondências de repositórios

Guia de Seleção de Formato

Ao usar 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 do contexto.
• Formato Markdown (use com moderação): Somente quando você realmente precisar do conteúdo completo da página, como ler um artigo inteiro para resumir 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 chamadas repetidas de scrape para URLs conhecidas, ou map + scrape para descobrir URLs primeiro, ou crawl para conteúdo completo de páginas)
• Quando você não tem certeza de qual página contém a informação (use search)

Erros comuns:

• Passar uma lista de URLs para uma única chamada de scrape. Chame scrape uma vez por URL no MCP. Se você precisar especificamente de uma operação de API em lote, use o endpoint de lote da API Firecrawl fora do MCP.
• Usar formato markdown por padrão (use formato JSON para extrair apenas o que você precisa).

Escolhendo o formato certo:

• Formato JSON (preferido): Para a maioria dos casos de uso, use formato JSON com um esquema para extrair apenas os dados específicos necessários. Isso mantém as respostas focadas e evita estouro do contexto.
• Formato Markdown: Somente quando a tarefa realmente exigir conteúdo completo da página (por exemplo, resumir 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 - preferido):

{
  "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 abrangente da marca (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 pessoalmente identificáveis redigidas.

Retorna:

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

2. 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)
• 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:

• Matriz de URLs encontradas no site

3. Ferramenta de Busca (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": "remote work stipend policies at tech companies",
    "highlights": true,
    "limit": 5,
    "lang": "en",
    "country": "us",
    "scrapeOptions": {
      "formats": ["markdown"],
      "onlyMainContent": true,
      "redactPII": true
    }
  }
}

Defina highlights como true para solicitar destaques relevantes à consulta ou false para manter os trechos originais da pesquisa. Omita para usar o comportamento padrão da API.

Para artigos científicos, consulte Ferramentas de Pesquisa: elas pesquisam resumos e texto completo de artigos, enquanto categories: ["research"] aqui filtra resultados web comuns para sites afiliados à pesquisa.

Retorna:

• Matriz de resultados de pesquisa (com conteúdo extraído opcional), além de 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:

"Compare políticas de auxílio para trabalho remoto entre empresas de tecnologia."

3b. 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 feedback bom.

Optar por não participar: 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 desativar o feedback no lado do servidor; nesse caso, a ferramenta é registrada, mas sempre retorna feedbackErrorCode: "TEAM_OPTED_OUT".

Campo mais importante: missingContent. É uma matriz de conteúdos específicos que o agente esperava encontrar, mas não encontrou. Uma entrada por tópico ausente — eles se agregam entre equipes e nos dizem o que indexar em seguida.

Limite diário de reembolso (por equipe, por dia UTC, padrão de 100 créditos). Quando o creditsRefundedToday de uma equipe atinge dailyRefundCap, envios adicionais 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 essa flag.

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? }.

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

Envia feedback estruturado para um trabalho de endpoint v2 concluído por meio de /v2/feedback. Use isso para feedback em nível de endpoint em trabalhos de scrape, parse, map ou search. Para qualidade de resultados 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.

Optar por não participar: 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? }.

4. Ferramenta de Crawl (firecrawl_crawl)

Inicia um trabalho de crawl, faz polling até atingir um estado terminal e retorna o status/dados finais do crawl.

Melhor para:

• Extrair conteúdo de várias 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 tokens são uma preocupação (use map + scrape para controle mais rígido)
• Quando você precisa de resultados rápidos (o crawl pode ser lento)

Aviso: As respostas do crawl podem ser muito grandes e exceder os limites de tokens. Limite a profundidade do crawl e o número de páginas, ou use map + scrape para controle mais rígido.

Erros comuns:

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

Exemplo de prompt:

"Obtenha todas as postagens do blog dos dois primeiros níveis de example.com/blog."

Exemplo de uso:

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

Retorna:

• Status e dados finais do crawl após polling interno, incluindo id, status, completed, total, creditsUsed, expiresAt, next e data. Use o id retornado com firecrawl_check_crawl_status se precisar verificar o trabalho novamente mais tarde.

5. Verificar Status do Crawl (firecrawl_check_crawl_status)

Verifique o status e os resultados de um trabalho de crawl existente por ID.

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

Retorna:

• A resposta inclui o status do trabalho de crawl:

6. Ferramenta de Parse (firecrawl_parse)

Analise arquivos locais ou referências de upload hospedadas com o endpoint /v2/parse do Firecrawl.

Melhor para: PDFs, documentos do Word, planilhas, arquivos HTML e outros documentos que precisam de saída em markdown ou JSON estruturado. O MCP hospedado suporta um fluxo de upload-ref em duas etapas; leituras diretas de arquivos locais exigem um FIRECRAWL_API_URL auto-hospedado.

Não recomendado para: URLs remotas (use scrape), vários arquivos em uma única chamada (chame parse uma vez por arquivo) ou ações exclusivas do navegador, como capturas de tela e cliques.

Fluxo do MCP hospedado: O MCP hospedado não pode ler o sistema de arquivos do chamador diretamente. Chame firecrawl_parse com filePath para receber um comando de upload de curta duração e nextToolCall, faça o upload do arquivo localmente e chame firecrawl_parse novamente com o uploadRef retornado. A criação da URL de upload hospedada requer autenticação do Firecrawl ou elegibilidade sem chave. No modo npx firecrawl-mcp local, a análise direta de arquivos atualmente requer FIRECRAWL_API_URL apontando para uma API Firecrawl auto-hospedada; um servidor local simples apenas com chave de API em nuvem não pode ler e fazer upload de arquivos por meio desta ferramenta.

Exemplo de uso:

{
  "name": "firecrawl_parse",
  "arguments": {
    "filePath": "/absolute/path/to/document.pdf",
    "formats": ["markdown"],
    "parsers": ["pdf"],
    "zeroDataRetention": true
  }
}

Retorna: Conteúdo do documento analisado ou instruções de upload hospedado com um nextToolCall.

7. Dados estruturados com Scrape JSON

Para dados estruturados de uma página conhecida, chame firecrawl_scrape uma vez por URL com formats: ["json"]. Coloque o prompt de extração e o esquema JSON em jsonOptions.

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

Para URLs desconhecidas ou pesquisa de múltiplas fontes, use firecrawl_search ou firecrawl_agent antes do Scrape.

8. Ferramenta de Agente (firecrawl_agent)

Agente autônomo de pesquisa na web. Esta é uma camada separada de agente de IA que navega independentemente pela internet, busca informações, navega por páginas e extrai dados estruturados com base na 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 — ele retorna um ID de trabalho imediatamente, e você faz polling de firecrawl_agent_status para verificar quando estiver concluído e recuperar os resultados.

Fluxo assíncrono:

1. Chame firecrawl_agent com seu prompt/esquema → retorna o ID do trabalho
2. Faça outro trabalho enquanto o agente pesquisa (pode levar minutos para consultas complexas)
3. Faça polling de firecrawl_agent_status com o ID do trabalho para verificar o progresso
4. 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ê conhece 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 de 10.000 caracteres)
• urls: Matriz 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 fazer polling dos 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" }
            }
          }
        }
      }
    }
  }
}

Depois faça polling 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 fazer polling dos resultados.

9. 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 fazer polling dos resultados após iniciar um agente.

Padrão de polling: A pesquisa do agente pode levar minutos para consultas complexas. Faça polling deste endpoint periodicamente (por exemplo, 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: A pesquisa terminou — a resposta inclui os dados extraídos
• failed: Ocorreu um erro

10. Ferramenta de Interação (firecrawl_interact)

Interaja com uma URL nova ou com uma página que já foi aberta por firecrawl_scrape.

Melhor para: Clicar, digitar, navegar e extrair estado de páginas dinâmicas sem restaurar as ferramentas de navegador obsoletas.

Opções de uso:

• Passe url para extrair e abrir uma página para interação em uma única chamada MCP.
• Passe scrapeId para continuar interagindo com uma página já extraída.
• Passe exatamente um de url ou scrapeId, além de prompt ou code.

Exemplo de uso:

{
  "name": "firecrawl_interact",
  "arguments": {
    "url": "https://example.com",
    "prompt": "Click the pricing link and summarize the visible plans"
  }
}

Retorna: Resultado da interação e, para o modo URL, o scrapeId derivado para acompanhamento ou limpeza.

11. Ferramenta de Parar Interação (firecrawl_interact_stop)

Pare uma sessão de interação para uma página extraída quando terminar de interagir.

{
  "name": "firecrawl_interact_stop",
  "arguments": {
    "scrapeId": "scrape-id-here"
  }
}

12. Ferramentas de Pesquisa (firecrawl_research_*)

Pesquise e inspecione artigos e repositórios do GitHub por meio das ferramentas MCP de pesquisa.

Cobre: resumos e texto completo de artigos em literatura biomédica, de ciências da vida e clínica (PubMed, bioRxiv, medRxiv), além de arXiv e outras fontes científicas.

Ferramentas de pesquisa disponíveis:

• firecrawl_research_search_papers: pesquise metadados e resumos de artigos com uma consulta em linguagem natural, com filtros opcionais de autor, categoria e data.
• firecrawl_research_inspect_paper: recupere metadados canônicos para um ID de artigo (arXiv, PMC, PMID ou DOI).
• firecrawl_research_related_papers: expanda a partir de um ou mais artigos âncora por meio do grafo de citações.
• firecrawl_research_read_paper: leia passagens de texto completo de um artigo específico.
• firecrawl_research_search_github: pesquise conteúdo indexado público de issues do GitHub, pull requests e README.

Melhor para: Revisão de literatura, consulta de artigos e fluxos de descoberta de repositórios onde o agente precisa de uma superfície de pesquisa focada em vez de extração web geral.

firecrawl_search com categories: ["research"] é uma superfície diferente: filtra resultados web comuns para sites afiliados à pesquisa e retorna trechos de páginas, não registros de artigos. Use essas ferramentas quando a pergunta for sobre a própria literatura, e passe várias formulações distintas da mesma pergunta — elas trazem artigos diferentes do que uma única consulta.

13. Ferramentas de Monitoramento (firecrawl_monitor_*)

Crie e gerencie monitores de página recorrentes. Os monitores executam scrapes ou crawls agendados, comparam cada resultado com o último snapshot 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 uma meta em linguagem simples
• Acompanhar o histórico de verificações e diffs em nível de página

Padrão recomendado de criação: Use page ou pages mais goal. O servidor MCP constrói a solicitação de monitoramento com um agendamento de 30 minutos e a API permite a avaliação automática de mudanças significativas.

A avaliação de mudanças significativas é executada automaticamente quando goal está definido. Os webhooks de página expõem isMeaningful e judgment em eventos monitor.page.

Escreva metas como instruções de monitoramento concisas de 2 a 3 frases. Diga o que deve acionar um alerta, preserve qualquer escopo que o usuário tenha fornecido e inclua exclusões específicas de intenção apenas quando for óbvio a partir da solicitação. Ruído genérico, como espaços em branco, alterações apenas de formatação, IDs de solicitação, parâmetros de rastreamento, metadados genéricos e elementos de página não relacionados já são tratados pelo avaliador, portanto não os repita em cada meta. Se o usuário for vago, mantenha a meta ampla; 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 avançadas de criação:

Passe body quando precisar de alvos de rastreamento, rastreamento de mudanças em 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 monitoramento:

• 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_delete: excluir um monitor (destrutivo; chame apenas quando o usuário pretender removê-lo).
• 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.

14. Ferramenta de Busca para Desenvolvedores (firecrawl_developer_search)

Pesquise em um índice construído para agentes de codificação. O índice cobre issues do GitHub, pull requests mesclados, READMEs de repositórios e sites de documentação selecionados.

Melhor para: Uma pergunta de programação — comportamento de código, uma biblioteca ou framework, um contrato de API, uma mensagem de erro ou um bug conhecido.

Argumentos:

{
  "name": "firecrawl_developer_search",
  "arguments": {
    "query": "how do I configure retries",
    "k": 10,
    "skills": "only"
  }
}

• query (obrigatório): a pergunta do desenvolvedor ou frase de busca.
• k: número de resultados classificados. O padrão é 10 e o máximo é 100.
• skills: defina como "only" para pesquisar apenas arquivos de habilidades de agente.

Retorna: Resultados classificados. Cada resultado contém um ID, um tipo de fonte (issue, pull_request, readme ou doc), uma URL, um título e as passagens correspondentes em markdown.

firecrawl_search com categories: ["developer"] pesquisa o mesmo índice junto aos resultados da web. Use esta ferramenta quando quiser as passagens e não os resultados da web. O endpoint somente de busca não expõe esta ferramenta; ele mantém seu conjunto fixo de seis ferramentas, e firecrawl_search alcança o índice de desenvolvedores lá.

Sistema de Logging

O servidor inclui logging abrangente:

• Status e progresso da operação
• Métricas de desempenho
• 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
[ERROR] Rate limit exceeded

Tratamento de Erros

O servidor fornece tratamento robusto de erros:

• Erros de limite de taxa da API exibidos ao cliente MCP
• Mensagens de erro detalhadas
• Resiliência de rede

Exemplo de resposta de erro:

{
  "content": [
    {
      "type": "text",
      "text": "Error: Rate limit exceeded"
    }
  ],
  "isError": true
}

Desenvolvimento

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

Contribuindo

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

Agradecimentos aos contribuidores

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

Agradecimentos a MCP.so e Klavis AI por hospedar e a @gstarwd, @xiangkaiz e @zihaolin96 por integrar nosso servidor.

Licença

Licença MIT - consulte o arquivo LICENSE para obter detalhes