Firecrawl MCP

Servidor MCP Firecrawl

Um servidor Model Context Protocol (MCP) que leva o Firecrawl para agentes de IA compatíveis com MCP — pesquise, raspe 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 um índice criado para agentes de codificação: issues do GitHub, pull requests mesclados, READMEs e documentações
• Raspe qualquer URL em dados limpos e estruturados
• Interaja com páginas — clique, navegue e opere
• Pesquisa aprofundada com agente autônomo
• Repetições 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 sob um site; defina limit, includePaths/excludePaths ou maxDiscoveryDepth para limitar.
• Use firecrawl_search quando 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 que você já raspou.
• 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 coisa quando precisar manter uma sessão de navegador aberta em muitas de suas próprias etapas com sua própria lógica de repetição e encerramento: cada chamada firecrawl_interact executa uma rodada 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, não executando 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 essa contagem, 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 remoto hospedado 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 humano 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 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 é 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 🖥️ 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 como configurar 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. Digite 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. Digite 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 raspagem web. Acesse o Composer via Command+L (Mac), selecione "Agente" ao lado do botão de envio e digite 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 Streamable

Para executar o servidor usando HTTP Streamable 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 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

Necessárias para a API na Nuvem

• FIRECRAWL_API_KEY: Sua chave de API do Firecrawl
  • Necessá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)

OAuth MCP (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 qualquer credencial que ele resolver para a API do Firecrawl como Authorization: Bearer ….

• Transportes de fluxo 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 raspagem/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 agrupado 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 agrupadas 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 Firecrawl fora do MCP.
• Se você precisar descobrir URLs em um site: use map
• Se você quiser pesquisar na web por informações: use search
• Se você tiver uma pergunta de programação (uma biblioteca, um contrato de API, uma mensagem de erro, um bug conhecido): use developer search
• Se você precisar de artigos científicos (literatura biomédica, de ciências da vida, clínica ou arXiv): use research tools — elas pesquisam resumos de artigos e texto completo. search com categories: ["research"] é uma coisa diferente: um filtro de site sobre resultados web comuns.
• Se você 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 você quiser analisar um site inteiro ou uma seção: use crawl (com limites!)
• Se você 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á raspou a página ou precisa de controle mais rígido de raspagem

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 raspada	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 desenvolvedor	results[] com passagens
agent	Pesquisa de múltiplas fontes, sites desconhecidos ou muitos	JSON (dados estruturados)
monitor	Verificações recorrentes de página	metadados de monitor/verificação e diffs
research	Pesquisa de artigos e repositórios GitHub	resultados de pesquisa e correspondências de repositório

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 de Scrape (firecrawl_scrape)

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

Ideal 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 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 batch 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 (ex.: 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 é necessário):

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

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

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

Formato de branding: Extrai identidade abrangente da marca (cores, fontes, tipografia, espaçamento, logo, 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 de Mapa (firecrawl_map)

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

Ideal 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:

• Array de URLs encontradas no site

3. Ferramenta de Busca (firecrawl_search)

Busca na web e opcionalmente extrai conteúdo dos resultados da busca.

Ideal 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 busca. Omita para usar o comportamento padrão da API.

Para artigos científicos, veja Research Tools: eles buscam em resumos de artigos e texto completo, enquanto categories: ["research"] aqui filtra resultados web comuns para sites afiliados à pesquisa.

Retorna:

• Array de resultados de busca (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 busca custa 2) e melhorar a qualidade da busca.

Exemplo de Prompt:

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

3b. Ferramenta de Feedback de Busca (firecrawl_search_feedback)

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

Chame esta ferramenta após cada busca 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 desabilitar o feedback no servidor; nesse caso, a ferramenta é registrada, mas sempre retorna feedbackErrorCode: "TEAM_OPTED_OUT".

Campo mais importante: missingContent. É um array 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 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 resultados de busca especificamente, prefira firecrawl_search_feedback porque inclui orientação específica de busca.

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.

Ideal 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 tokens são uma preocupação (use map + scrape para controle mais rígido)
• Quando você precisa de resultados rápidos (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 de Parse (firecrawl_parse)

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

Ideal 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 em duas etapas; leituras diretas de arquivos locais exigem um FIRECRAWL_API_URL auto-hospedado.

Não recomendado para: URLs remotas (use scrape), múltiplos arquivos em uma única chamada (chame parse uma vez por arquivo) ou ações exclusivas de 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 então 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 apenas com chave de API em nuvem não pode ler e fazer upload de arquivos através 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 multi-fonte.

8. Ferramenta de Agente (firecrawl_agent)

Agente autônomo de pesquisa web que retorna dados estruturados quando você não sabe 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 buscas web, segue links, lê páginas e coleta dados autonomamente. Isso roda assincronamente — retorna um ID de trabalho imediatamente, e você faz polling em firecrawl_agent_status para verificar quando concluir 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 em 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

Ideal para:

• Tarefas de pesquisa complexas onde você não sabe as URLs exatas
• Coleta de dados multi-fonte
• Encontrar informações dispersas na 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 de 10.000 caracteres)
• urls: Array 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 seus antecedentes"

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 neste 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

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 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 URL, o scrapeId derivado para acompanhamento ou limpeza.

11. Ferramenta Parar Interação (firecrawl_interact_stop)

Encerra uma sessão de interação para uma página raspada quando você 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.

Abrange: resumos e textos completos 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 trechos de texto completo de um artigo específico.

Melhor para: Revisão de literatura, consulta de artigos e fluxos de descoberta de repositórios em que 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 própria literatura e passe várias formulações distintas da mesma pergunta — elas trazem artigos diferentes de uma única consulta.

13. Ferramentas de Monitoramento (firecrawl_monitor_*)

Crie e gerencie monitores de página 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 uma meta 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 de mudanças significativas automaticamente.

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

Escreva metas como instruções de monitor concisas de 2 a 3 frases. 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 forem óbvias a partir da 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á é tratado pelo avaliador, portanto não repita isso 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."
  }
}

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 de criação avançadas:

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 abrange 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 do agente.

Retorna: Resultados classificados. Cada resultado traz um ID, um tipo de fonte (issue, pull_request, readme ou doc), uma URL, um título e os trechos correspondentes em markdown.

firecrawl_search com categories: ["developer"] pesquisa o mesmo índice junto aos resultados web. Use esta ferramenta quando quiser os trechos 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 das operações
• 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 seu 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 pela hospedagem e a @gstarwd, @xiangkaiz e @zihaolin96 pela integração do nosso servidor.

Licença

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