Firecrawl

Servidor MCP Firecrawl

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

Um grande agradecimento a @vrknetha e @knacklabs pela implementação inicial!

Recursos

• Pesquise na web e obtenha o conteúdo completo da página
• Pesquise um índice criado para agentes de codificação: issues do GitHub, pull requests mesclados, READMEs e documentações
• 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 limite de taxa
• Suporte para nuvem e auto-hospedagem
• Suporte SSE

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

Quando Usar Este Servidor

• Use firecrawl_scrape quando você tiver uma URL conhecida e quiser seu conteúdo como markdown ou como JSON correspondente a um esquema que você fornecer.
• Use firecrawl_map quando precisar descobrir URLs em um site sem buscar o conteúdo delas.
• Use firecrawl_crawl quando precisar de conteúdo de muitas páginas de um site; defina limit, includePaths/excludePaths ou maxDiscoveryDepth para limitar.
• Use firecrawl_search quando você estiver começando com uma consulta em vez de uma URL e quiser resultados web classificados; adicione scrapeOptions se também quiser que o conteúdo da página seja buscado na mesma chamada (o endpoint somente de pesquisa nunca busca conteúdo).
• Use firecrawl_interact quando uma página precisar de uma ação de clique, digitação ou navegação antes que você possa lê-la — passe um url para uma página nova ou um scrapeId para continuar em uma página que você já extraiu.
• Use as ferramentas firecrawl_monitor_* quando a mesma página precisar ser verificada em um agendamento recorrente com diffs e alertas de alteração, em vez de ser buscada uma única vez.
• Considere outra solução quando precisar manter uma sessão de navegador aberta em várias etapas suas, com sua própria lógica de tentativas e encerramento: cada chamada de firecrawl_interact executa uma rodada de prompt ou code até a conclusão e retorna o controle — a sessão pode persistir entre chamadas via scrapeId e termina com firecrawl_interact_stop, mas você não pode conduzi-la interativamente passo a passo pelo lado do cliente em uma única chamada.

Este servidor lista 25 ferramentas quando o perfil completo é registrado com as configurações padrão (ferramentas de feedback incluídas, sem execução em modo local sem chave). Definir FIRECRAWL_NO_SEARCH_FEEDBACK=1 e/ou FIRECRAWL_NO_ENDPOINT_FEEDBACK=1 remove as ferramentas de feedback correspondentes e reduz esse número, assim como a inicialização local sem chave. Para clientes com limite de slots de ferramentas: o endpoint hospedado sem chave (https://mcp.firecrawl.dev/v2/mcp, sem chave de API) expõe apenas 3 — firecrawl_scrape, firecrawl_search, firecrawl_parse — e o endpoint dedicado somente de pesquisa (https://mcp.firecrawl.dev/v2/mcp-search) expõe um conjunto fixo de 6 ferramentas somente leitura.

Instalação

MCP hospedado (nível gratuito sem chave)

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

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

No nível gratuito 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 de conta interativa, 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 secreta 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 de pesquisa também é hospedada em:

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

Ela expõe um conjunto fixo de seis ferramentas somente leitura: firecrawl_search, firecrawl_developer_search e as quatro ferramentas firecrawl_research_*. Ela não realiza busca de conteúdo de página 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 🖥️ Observação: 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 Servidor 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 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 "Agente" 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 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órias para a API na Nuvem

• FIRECRAWL_API_KEY: Sua chave de API do Firecrawl
  • Obrigatória ao usar a API na nuvem (padrão)
  • Opcional ao usar uma 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 na nuvem será usada (requer chave de API)

MCP OAuth (tokens de acesso Bearer)

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

• Transports 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_…). 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 do 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 na 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ê souber a URL exata que deseja: use scrape (com formato JSON para dados estruturados)
• Se você tiver 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 do Firecrawl fora do MCP.
• Se precisar descobrir URLs em um site: use map
• Se quiser pesquisar na web por informações: use search
• Se tiver uma pergunta de programação (uma biblioteca, um contrato de API, uma mensagem de erro, um bug conhecido): use developer search
• Se precisar de artigos científicos (literatura biomédica, de ciências da vida, clínica ou arXiv): use ferramentas de pesquisa — elas buscam resumos e textos completos de artigos. search com categories: ["research"] é uma coisa diferente: um filtro de site sobre resultados web comuns.
• Se precisar de pesquisa de múltiplas fontes que retorne dados estruturados, não souber as URLs, ou a resposta abranger vários sites (uma entidade mais seus campos, uma lista, um conjunto de dados): use agent
• Se quiser analisar um site ou seção inteira: use crawl (com limites!)
• Se precisar de automação interativa de navegador (clique, digite, navegue): use interact com uma URL para uma página nova, ou scrape + interact quando você já extraiu a página ou precisa de um controle mais rigoroso da 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 desenvolvimento	results[] com passagens
agent	Pesquisa de múltiplas fontes, sites desconhecidos ou muitos	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 schema 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)

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

Melhor para:

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

Não recomendado para:

• Extrair conteúdo de várias 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 o formato markdown por padrão (use o formato JSON para extrair apenas o que você precisa).

Escolhendo o formato certo:

• Formato JSON (preferido): Para a maioria dos casos de uso, use o formato JSON com um schema 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 o 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 o conteúdo completo for 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 pessoais identificáveis removidas.

Retorna:

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

2. Ferramenta Map (firecrawl_map)

Mapeia 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 Search (firecrawl_search)

Pesquisa na web e opcionalmente extrai 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)

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 para 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 Research Tools: eles 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 em 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 concluído do endpoint v2 por meio de /v2/feedback. Use isso para feedback no nível do 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 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)

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)

Verifica 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 Parse (firecrawl_parse)

Analisa 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 markdown ou JSON estruturado. O MCP hospedado suporta um fluxo de upload-referência 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 depois chame firecrawl_parse novamente com o uploadRef retornado. A criação da URL de upload hospedada requer autenticação Firecrawl ou elegibilidade sem chave. No modo local npx firecrawl-mcp, a análise direta de arquivos atualmente requer FIRECRAWL_API_URL apontando para uma API Firecrawl auto-hospedada; um servidor local simples com apenas 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 schema 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"]
      }
    }
  }
}

Quando as URLs não são conhecidas ou os dados abrangem vários sites, use firecrawl_agent para pesquisa de múltiplas fontes.

8. Ferramenta Agent (firecrawl_agent)

Agente autônomo de pesquisa web que retorna dados estruturados quando você não conhece as URLs ou a resposta abrange vários sites. Descreva os campos que você precisa, opcionalmente passe um schema JSON e URLs iniciais, e o agente pesquisa, navega, lê páginas e retorna JSON montado entre fontes. Use para uma entidade e seus campos, para listas e conjuntos de dados, e para páginas que precisam de navegação para alcançar os dados. Para uma URL conhecida, use firecrawl_scrape com formato JSON.

Como funciona:

O agente realiza pesquisas web, segue links, lê páginas e coleta dados autonomamente. 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/schema → retorna 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 conhece 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: Schema 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 para 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)

Verifica o status de um trabalho de agente e recupera os resultados quando concluído. Use 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: Pesquisa concluída - a resposta inclui os dados extraídos
• failed: Ocorreu um erro

10. Ferramenta Interact (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 o estado de páginas dinâmicas sem restaurar as ferramentas de navegador obsoletas.

Opções de uso:

• Passe url para raspar e abrir uma página para interação em uma única chamada MCP.
• Passe scrapeId para continuar interagindo com uma página já raspada.
• 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, no modo de URL, o scrapeId derivado para acompanhamento ou limpeza.

11. Ferramenta Parar Interação (firecrawl_interact_stop)

Pare uma sessão de interação para uma página raspada 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 de artigos e texto completo 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.

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 raspagem 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 literatura em si, 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áginas recorrentes. Os monitores executam raspagens 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 inglês simples
• Acompanhar o histórico de verificações e diferenças no nível da página

Padrão recomendado de criação:

Use page ou pages mais goal. O servidor MCP monta a solicitação de monitor com um agendamento de 30 minutos e a API ativa 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 objetivos como instruções concisas de 2 a 3 frases para o monitor. Diga o que deve acionar um alerta, preserve qualquer escopo que o usuário tenha dado e inclua exclusões específicas de intenção apenas quando for óbvio pela solicitação. Ruído genérico, como espaços em branco, mudanças 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, então não os repita em cada objetivo. 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."
  }
}

Várias 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 monitor:

• firecrawl_monitor_list: liste monitores.
• firecrawl_monitor_get: obtenha um monitor.
• firecrawl_monitor_update: atualize campos, incluindo goal, judgeEnabled, webhook e notification.
• firecrawl_monitor_run: acione uma verificação agora.
• firecrawl_monitor_delete: exclua um monitor (destrutivo; chame apenas quando o usuário pretender removê-lo).
• firecrawl_monitor_checks: liste verificações, opcionalmente filtradas por status.
• firecrawl_monitor_check: obtenha resultados no nível da página, incluindo diff, snapshot, judgment.meaningful e judgment.meaningfulChanges.

14. Ferramenta de Pesquisa para Desenvolvedores (firecrawl_developer_search)

Pesquise em um índice criado 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 ou frase de pesquisa do desenvolvedor.
• 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 carrega 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 com os resultados web. Use esta ferramenta quando quiser as passagens correspondentes, o filtro skills ou nenhum resultado web na resposta. O endpoint somente de pesquisa expõe ambas as ferramentas, e a mesma escolha se aplica lá.

Sistema de Registro

O servidor inclui registro abrangente:

• Status e progresso da operação
• Métricas de desempenho
• Rastreamento de limites de taxa
• Condições de erro

Exemplos de mensagens de registro:

[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 sua branch de funcionalidade
3. Execute os testes: npm test
4. Envie um pull request

Agradecimentos aos contribuidores

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

Agradecemos ao 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