Firecrawl MCP

Servidor MCP do Firecrawl

Um servidor Model Context Protocol (MCP) que traz o Firecrawl, a API de contexto para agentes de IA, para clientes compatíveis com MCP: pesquise, faça scraping e interaja com a web ao vivo e receba de volta Markdown limpo ou dados estruturados.

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

Recursos

• Pesquise na web, opcionalmente com o conteúdo completo da página para cada resultado
• Pesquise em índices de fontes para desenvolvedores (issues do GitHub, pull requests mesclados, READMEs e documentações), fontes do governo dos EUA e artigos científicos (PubMed, bioRxiv, medRxiv, arXiv)
• Faça scraping de qualquer URL em Markdown limpo ou JSON estruturado
• Analise PDFs e documentos
• Rastreie um site para obter conteúdo de várias páginas ou mapeie-o para descobrir suas URLs
• Interaja com páginas em um navegador real: clique, digite, preencha formulários e navegue por páginas dinâmicas
• Execute tarefas de Agent para pesquisa multi-fonte que retorna dados estruturados
• Monitore páginas e seja notificado quando o conteúdo delas mudar
• Verifique o uso atual e histórico de créditos do Firecrawl
• Novas tentativas automáticas e limitação de taxa
• Suporte a nuvem e auto-hospedagem
• Suporte a 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 o conteúdo dela como markdown ou como JSON correspondente a um schema 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 várias páginas de um site; defina limit, includePaths/excludePaths ou maxDiscoveryDepth para limitar.
• Use firecrawl_search quando estiver partindo de uma consulta em vez de uma URL e quiser resultados web classificados. Os resultados trazem trechos; busque as páginas completas com firecrawl_scrape nas URLs de que precisar. scrapeOptions busca a página de cada resultado na mesma chamada e cobra cada uma como um scrape, então reserve-o para o texto completo de poucos resultados (o endpoint somente de busca nunca busca conteúdo).
• Use firecrawl_interact quando uma página precisar de uma ação de clique, digitação ou navegação antes de você poder lê-la: passe um url para uma página nova ou um scrapeId para continuar em uma que você já fez scraping.
• Use as ferramentas firecrawl_monitor_* quando a mesma página precisar ser verificada em um cronograma recorrente com diffs e alertas de mudança, em vez de buscada uma única vez.
• Use firecrawl_credit_usage para verificar os créditos restantes ou em que os créditos foram gastos, por mês ou dia, opcionalmente detalhados por endpoint ou chave de API.
• Considere outra opção quando você precisar manter uma sessão de navegador aberta ao longo de muitos passos seus, com sua própria lógica de novas tentativas e encerramento: cada chamada de firecrawl_interact executa um turno de prompt ou code até a conclusão e devolve 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 do lado do cliente dentro de uma única chamada.

Este servidor lista 27 ferramentas quando o perfil completo é registrado com as configurações padrão (ferramentas de feedback incluídas, não em execução no 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 busca (https://mcp.firecrawl.dev/v2/mcp-search) expõe um conjunto fixo de 9 ferramentas (busca, busca para desenvolvedores, governamental e científica, além de consulta e execução do catálogo Alexandria).

Instalação

MCP Hospedado (nível gratuito sem chave)

Conecte-se ao servidor remoto hospedado sem nenhuma 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 a pessoa puder se cadastrar. Isso desbloqueia o conjunto completo de ferramentas e limites maiores.

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 por chave de API (por exemplo, uma integração não assistida), 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 do agente para instruções específicas de cada cliente.

Nomeando sua integração

Uma integração que se conecta via HTTP pode se nomear com um cabeçalho X-Firecrawl-Origin, por exemplo X-Firecrawl-Origin: my-agent. O servidor o reporta ao Firecrawl como a origem da requisição mcp-my-agent@<server version>, no lugar do nome do cliente ou User-Agent que reportaria de outra forma. Use letras, dígitos e hífens: cada sequência de outros caracteres vira um hífen, hífens iniciais e finais são removidos, e o nome é cortado em 48 caracteres. Os resultados das ferramentas não são afetados; apenas a origem enviada à API do Firecrawl (e passada ao beforeKeylessRequest de um embedder) muda.

Endpoint somente de busca

Uma superfície de busca de escopo fixo também está hospedada em:

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

Ela expõe um conjunto fixo de nove ferramentas: firecrawl_search, firecrawl_developer_search, firecrawl_gov_search, as quatro ferramentas firecrawl_research_* e as duas ferramentas Alexandria firecrawl_find_tools e firecrawl_scrape. Seu firecrawl_search não busca conteúdo de página.

Executando com npx

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

Instalação Manual

npm install -g firecrawl-mcp

Executando no Cursor

Configurando o Cursor 🖥️ Nota: Requer Cursor versão 0.45.6+ Para as instruções de configuração mais atualizadas, consulte a documentação oficial do Cursor sobre configuração de servidores MCP: Guia de Configuração 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 Features > MCP Servers
3. Clique em "+ Add new global MCP server"
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 Features > MCP Servers
3. Clique em "+ Add New MCP Server"
4. Insira o seguinte:
   • Nome: "firecrawl-mcp" (ou o nome de sua preferência)
   • Tipo: "command"
   • Comando: env FIRECRAWL_API_KEY=your-api-key npx -y firecrawl-mcp

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

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

Após adicionar, atualize a lista de servidores MCP para ver as novas ferramentas. O Composer Agent usará automaticamente o Firecrawl MCP quando apropriado, mas você pode solicitá-lo explicitamente descrevendo o que precisa 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

Neste modo, o servidor só responde a requisições endereçadas a localhost, 127.0.0.1 ou [::1] (em qualquer porta), além do endereço em HOST quando ele não for 0.0.0.0 ou ::. Uma requisição cujo cabeçalho Host nomeie outro host, ou cujo cabeçalho Origin nomeie outro site, recebe 403, e os cabeçalhos CORS ecoam uma origem permitida em vez de *. Requisições GET e HEAD para /health são respondidas independentemente do host, para que as verificações de integridade continuem funcionando, e o servidor registra uma linha nomeando FIRECRAWL_MCP_ALLOWED_HOSTS para cada requisição que recusa. Isso impede que páginas web que você visita chamem o servidor local por meio de DNS rebinding ou requisições cross-origin e usem seu FIRECRAWL_API_KEY.

Para alcançar o servidor sob outro nome ou endereço, como um hostname atrás de um proxy reverso ou um IP de LAN, liste-o em FIRECRAWL_MCP_ALLOWED_HOSTS (separado por vírgulas; portas são ignoradas). A mesma lista decide quais origens de navegador podem chamar o servidor. Um proxy reverso na mesma máquina pode manter o endereço de bind padrão:

env HTTP_STREAMABLE_SERVER=true FIRECRAWL_API_KEY=fc-YOUR_API_KEY \
  FIRECRAWL_MCP_ALLOWED_HOSTS=mcp.home.lan npx -y firecrawl-mcp

Clientes em outras máquinas também precisam que o servidor escute em um endereço não-loopback, então defina HOST também. Todo cliente que conseguir alcançar a porta será então atendido com o FIRECRAWL_API_KEY do servidor, então faça isso apenas em uma rede confiável:

env HTTP_STREAMABLE_SERVER=true FIRECRAWL_API_KEY=fc-YOUR_API_KEY HOST=0.0.0.0 \
  FIRECRAWL_MCP_ALLOWED_HOSTS=192.168.1.20 npx -y firecrawl-mcp

FIRECRAWL_MCP_ALLOWED_HOSTS=* desativa a verificação e restaura o cabeçalho CORS curinga. Faça isso apenas quando algo à frente do servidor verificar hosts e origens por conta própria.

Executando com Docker

A imagem ghcr.io/firecrawl/firecrawl-mcp-server executa o mesmo servidor que npx -y firecrawl-mcp. Toda build a partir de main é marcada como latest, v<package version> e sha-<commit sha>. v<package version> passa para a build mais recente dessa versão, então fixe sha-<commit sha> (ou um digest) quando precisar de uma imagem fixa.

stdio (o padrão), para clientes MCP que iniciam o servidor como um comando:

docker run -i --rm -e FIRECRAWL_API_KEY=fc-YOUR_API_KEY ghcr.io/firecrawl/firecrawl-mcp-server:latest

{
  "mcpServers": {
    "firecrawl-mcp": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "FIRECRAWL_API_KEY", "ghcr.io/firecrawl/firecrawl-mcp-server:latest"],
      "env": {
        "FIRECRAWL_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Streamable HTTP, servido em http://localhost:3000/mcp:

docker run --rm -p 127.0.0.1:3000:3000 \
  -e HTTP_STREAMABLE_SERVER=true \
  -e FIRECRAWL_API_KEY=fc-YOUR_API_KEY \
  ghcr.io/firecrawl/firecrawl-mcp-server:latest

A imagem define HOST=0.0.0.0 e PORT=3000; substitua PORT (e o mapeamento de -p) para escutar em outro lugar. O servidor usa o FIRECRAWL_API_KEY do contêiner para requisições que não enviam sua própria credencial, então o exemplo publica a porta apenas em 127.0.0.1; não a exponha mais amplamente a menos que os clientes devam fornecer sua própria chave. Defina FIRECRAWL_API_URL para usar uma API Firecrawl auto-hospedada. O contêiner é executado como o usuário sem privilégios node. O servidor responde apenas a localhost, 127.0.0.1 e [::1] nos cabeçalhos Host e Origin, então o mapeamento -p 127.0.0.1:3000:3000 funciona como está; para alcançá-lo sob outro nome, defina -e FIRECRAWL_MCP_ALLOWED_HOSTS=<host> (consulte Modo local do Streamable HTTP).

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 User Settings (JSON) no VS Code. Você pode fazer isso pressionando Ctrl + Shift + P e digitando Preferences: Open User Settings (JSON).

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

Opcionalmente, você pode adicioná-lo a um arquivo chamado .vscode/mcp.json em seu workspace. Isso permitirá compartilhar 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)
• FIRECRAWL_INTEGRATION (Opcional): Tag de integração para apps que iniciam este servidor, como uma extensão de editor
  • Enviada como o campo integration de requisições de scrape, batch scrape, crawl, map, search, extract, agent, parse, interact e feedback
  • Use um valor que comece com _, por exemplo _zed

Modo HTTP local

• FIRECRAWL_MCP_ALLOWED_HOSTS (Opcional): Nomes de host ou endereços extras com os quais o servidor responde com HTTP_STREAMABLE_SERVER=true ou SSE_LOCAL=true, separados por vírgula
  • localhost, 127.0.0.1, [::1] e um HOST sem curinga são sempre permitidos; as portas são ignoradas
  • Requisições cujo cabeçalho Host ou Origin nomeie qualquer outro host recebem 403, exceto requisições GET e HEAD para /health
  • * desativa a verificação; não é usado com CLOUD_SERVICE=true, que responde a qualquer host

MCP OAuth (tokens de acesso Bearer)

O Firecrawl emite tokens de acesso OAuth (fco_…) por meio 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 requisições MCP. Um token Bearer OAuth tem precedência sobre x-firecrawl-api-key / x-api-key quando ambos estão presentes.
• stdio: Use FIRECRAWL_OAUTH_TOKEN para um token de acesso estático, ou continue usando FIRECRAWL_API_KEY para uma chave de API.

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

CLOUD_SERVICE=true

CLOUD_SERVICE=true serve as ferramentas via HTTP streamable em PORT (padrão 3000, vinculado a 0.0.0.0) com padrões mais rígidos: toda requisição deve carregar uma credencial (uma chave de API ou um token de acesso OAuth), o scrape é somente leitura (veja a ferramenta de scrape abaixo) e firecrawl_parse aceita apenas uploads.

FASTMCP_ENDPOINT seleciona a superfície de ferramentas: /v2/mcp (padrão) para o conjunto completo de ferramentas, /v2/mcp-oauth para a superfície de conta, ou /v2/mcp-search para as ferramentas somente de busca (isso também requer FIRECRAWL_MCP_SEARCH_OAUTH_ONLY=true). Com a superfície completa, uma instância somente de busca também inicia na porta 3001; defina FIRECRAWL_MCP_SEARCH_ENABLED=false para desativá-la.

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 o 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ê precisa especificamente de uma única operação de API em lote, use o endpoint em lote da API do Firecrawl fora do MCP.
• Se você precisa descobrir URLs em um site: use map
• Se você quer buscar informações na web: 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ê tem uma pergunta jurídica ou regulatória (um estatuto, regulamento, código, opinião judicial ou outra publicação do governo dos EUA): use o Firecrawl Government Index
• Se você precisa de artigos científicos (literatura biomédica, de ciências da vida, clínica ou arXiv): use as research tools, que buscam resumos e texto completo de artigos. search com categories: ["research"] é outra coisa: um filtro de sites sobre resultados comuns da web.
• Se você precisa de pesquisa multi-fonte que retorne dados estruturados, não sabe as URLs, ou a resposta abrange vários sites (uma entidade e seus campos, uma lista, um conjunto de dados): use agent
• Se você quer analisar um site ou seção inteira: 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á fez o scrape da página ou precisa de controle mais refinado do scrape
• Se você precisa de dados de um provedor catalogado (Alexandria): busque com sources: ["alexandria"], inspecione o contrato selecionado com find_tools e execute-o com scrape alexandria

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 o 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	Busca na web por informações	results[]
find_tools	Navegação do catálogo Alexandria e busca de URL	provedores, contratos de ferramentas e navegação nextTool
developer	Perguntas de programação sobre fontes de desenvolvedor	results[] com passagens
gov	Legislação primária e material regulatório dos EUA	results[] com trechos
agent	Pesquisa multi-fonte, 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 do 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 o estouro da janela de contexto.
• Formato Markdown (use com moderação): Apenas 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)

Raspe 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 o conteúdo completo das 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ê precisa especificamente de uma única operação de API em lote, use o endpoint em lote da API do 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 o estouro da janela de contexto.
• Formato Markdown: Apenas 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 em 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 a identidade de marca abrangente (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 de identificação pessoal redigidas. Com CLOUD_SERVICE=true: o scrape é somente leitura. Ele não usa actions de navegador e não pode aceitar termos de provedores. Um profile nomeado carrega o estado de navegador salvo sem salvar alterações nele, e o firecrawl_search do endpoint completo trata scrapeOptions.profile da mesma forma. Para salvar o estado do navegador em um perfil, abra a página com firecrawl_interact (veja abaixo). Um administrador da organização aceita os termos no painel.

Retorna:

• Dados estruturados em 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 raspar
• 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 Search (firecrawl_search)

Busque na web e, opcionalmente, extraia conteúdo dos resultados da busca.

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

Para obter o texto completo de alguns resultados na mesma chamada, adicione "scrapeOptions": { "formats": ["markdown"], "onlyMainContent": true }. Cada resultado buscado é cobrado como um scrape, então para a maioria das perguntas use os trechos e firecrawl_scrape apenas as URLs necessárias.

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

Adicione "sources": ["alexandria"] para descoberta semântica de ferramentas em data.tools, opcionalmente combinada com web/news/images. Uma consulta é obrigatória. Use firecrawl_find_tools para consulta contextual e divulgação progressiva; veja Alexandria Tools.

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

Retorna:

• Resultados de busca agrupados por fonte (data.web, data.images, data.news), com conteúdo raspado opcional, além de um campo id. Cada resultado carrega um source e um position indexado a partir de 1, numerado a partir de 1 dentro do seu próprio grupo — copie o par diretamente para o valuableResults de firecrawl_search_feedback em vez de contar elementos do array. 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 entre 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 isto 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 poderão 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. É um array de trechos específicos de conteúdo que o agente esperava encontrar, mas não encontrou. Uma entrada por tópico ausente; esses dados são agregados entre equipes e nos indicam o que indexar em seguida. Para obter resultados úteis, use valuableResults com o par source/position marcado em cada resultado — os resultados são agrupados e cada grupo é numerado a partir de 1 de forma independente, portanto ambos são obrigatórios. Liste todos os resultados úteis (resultados não listados são tratados como não úteis) e reserve valuableSources para URLs úteis que não estavam entre os resultados retornados.

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 restante do dia UTC ao verem esse sinalizador.

Exemplo de uso:

{
  "name": "firecrawl_search_feedback",
  "arguments": {
    "searchId": "0193f6c5-1234-7890-abcd-1234567890ab",
    "rating": "good",
    "valuableResults": [
      { "source": "web", "position": 1 },
      { "source": "web", "position": 3 },
      { "source": "news", "position": 2, "reason": "Broke the pricing change." }
    ],
    "valuableSources": [
      {
        "url": "https://docs.firecrawl.dev/pricing",
        "reason": "Not in the results; found via a result's pricing link. Answered the question."
      }
    ],
    "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 de { success, feedbackId, creditsRefunded, alreadySubmitted? }.

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

Envia feedback estruturado para um job concluído de endpoint v2 por meio de /v2/feedback. Use isto para feedback no nível do endpoint em jobs scrape, parse, map ou search. Para qualidade de resultados de busca especificamente, prefira firecrawl_search_feedback, pois ele inclui orientações específicas 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.

Opt out: 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 poderão 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 de { success, feedbackId, creditsRefunded, creditsRefundedToday?, dailyRefundCap?, dailyCapReached?, websiteCapReached?, alreadySubmitted?, warning? }.

4. Ferramenta de Crawl (firecrawl_crawl)

Inicia um job 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 limites de tokens são uma preocupação (use map + scrape para maior controle)
• Quando você precisa de resultados rápidos (o crawl pode ser lento)

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

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 todos os posts de 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 job novamente mais tarde.

5. Verificar Status do Crawl (firecrawl_check_crawl_status)

Verifica o status e os resultados de um job de crawl existente por ID.

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

Retorna:

• A resposta inclui o status do job de crawl:

6. Ferramenta de 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 em markdown ou JSON estruturado. O endpoint hospedado usa 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), vários arquivos em uma única chamada (chame parse uma vez por arquivo) ou ações exclusivas de navegador, como capturas de tela e cliques.

Endpoint hospedado: ele não consegue ler seu sistema de arquivos. 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 etapa de upload exige autenticação do Firecrawl ou o nível sem chave. No modo local npx firecrawl-mcp, a análise direta de arquivos atualmente exige FIRECRAWL_API_URL apontando para uma API Firecrawl auto-hospedada; um servidor local simples apenas com chave de API da nuvem não consegue ler e enviar arquivos por esta 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"]
      }
    }
  }
}

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 na web que retorna dados estruturados quando você não conhece as URLs ou a resposta abrange vários sites. Descreva os campos de que precisa, opcionalmente passe um esquema JSON e URLs de seed, e o agente pesquisa, navega, lê páginas e retorna JSON montado a partir de várias fontes. Use-o para uma entidade mais seus campos, para listas e conjuntos de dados, e para páginas que exigem navegação para chegar aos dados. Para uma URL conhecida, use firecrawl_scrape com formato JSON em vez disso.

Como funciona:

O agente realiza buscas na web, segue links, lê páginas e reúne dados de forma autônoma. Isso é executado de forma assíncrona — ele retorna um ID de job imediatamente, e você faz polling em 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 job
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 job para verificar o progresso
4. Quando o status for "completed", a resposta inclui os dados extraídos

Melhor para:

• Tarefas de pesquisa complexas em que você não conhece as URLs exatas
• Coleta de dados de várias fontes
• Encontrar informações dispersas pela web
• Tarefas em que você pode fazer outro trabalho enquanto espera pelos resultados

Não recomendado para:

• Scraping simples de página única em que você conhece a URL (use scrape com formato JSON — mais rápido e mais barato)

Argumentos:

• prompt: Descrição em linguagem natural dos dados que você deseja (obrigatório, máx. 10.000 caracteres)
• urls: Array opcional de URLs para focar o agente em páginas específicas
• schema: Esquema JSON opcional para saída estruturada
• effort: Opcional. Orçamento de raciocínio "low", "medium" ou "high" para a tarefa do agente.
• maxCredits: Inteiro positivo opcional. Limite de gasto em créditos para esta execução. A API usa 2.500 por padrão quando omitido, e limita uma requisição gratuita a 2.500.
• strictConstrainToURLs: Booleano opcional. Se true, o agente visita apenas as URLs em urls.
• threadId: Opcional. Continua uma thread existente: o threadId de um resultado anterior de firecrawl_agent ou firecrawl_agent_status. Omita para iniciar uma nova thread. Em um follow-up, as configurações omitidas de mode, urls, schema e exchange são herdadas do turno anterior.
• mode: Opcional. "extract" (padrão) retorna o resultado estruturado completo a cada turno. "chat" permite que um follow-up que não pede novos dados receba uma resposta curta em message em vez de uma nova execução; exchange.requireApproval exige isso.
• exchange: Opcional. Configurações do provedor Alexandria para este turno, encaminhadas como estão para POST /v2/agent:
  • enabled, toolkits (até 5 slugs de provedor), maxCalls (1 a 30), requireApproval (chamadas pagas encerram o turno com um pendingApproval; exige mode: "chat" na mesma chamada, mesmo em um follow-up)
  • onTermsRequired: o que fazer quando um provedor Alexandria que o agente usaria exige termos de dados que sua equipe não aceitou. Provedores restritos nunca são chamados em nenhum modo. Omitido em um follow-up, mantém o valor do turno anterior.
    • "skip" (padrão): responde apenas com provedores aceitos. exchange.skippedProviders no resultado de status lista os provedores restritos que teriam ajudado.
    • "ask": o mesmo, mais um pendingApproval de termos e exchange.requiresAction com o ID de aprovação e os requisitos do provedor. Leia os termos com terms/show; um administrador da organização os aceita no painel do Firecrawl.
  • approve: { approvalId, callIds?, always? } responde sim ao pendingApproval em que o turno anterior terminou. callIds e always se aplicam apenas a aprovações de chamadas pagas.
  • decline: { approvalId } responde não. Uma oferta de termos recusada mantém esses provedores fora do restante da thread.
  • approve e decline exigem threadId, e apenas um deles pode ser enviado.

Termos do provedor (modo de perguntar): não há modo de aceitação automática. Quando um turno termina em uma oferta de termos, o resultado de status carrega pendingApproval (kind: "terms") e exchange.requiresAction com o approvalId e os requisitos do provedor. Qualquer descritor terms/accept nesse payload da API não está disponível via MCP. Para usar o provedor:

1. Mostre ao usuário os termos (terms/show até firecrawl_scrape com alexandria).
2. Oriente um administrador da organização a aceitar os termos na URL do provedor, ou em configurações de fontes de dados. Uma solicitação de dados não é consentimento.
3. Aguarde o administrador confirmar a aceitação no painel.
4. Continue a mesma thread: chame firecrawl_agent com o mesmo threadId e exchange.approve: { "approvalId": "..." }. Isso retoma a pesquisa e não aceita os termos.

Se o usuário disser não, chame firecrawl_agent com o mesmo threadId e exchange.decline: { "approvalId": "..." } em vez disso.

Exemplo de prompt:

"Encontre os fundadores do Firecrawl e seus históricos"

Exemplo de uso (iniciar agente e 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" }
            }
          }
        }
      }
    }
  }
}

Em seguida, faça polling com firecrawl_agent_status usando o ID de job retornado.

Exemplo de uso (com URLs — o 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"
  }
}

Exemplo de uso (follow-up na mesma thread):

{
  "name": "firecrawl_agent",
  "arguments": {
    "prompt": "Only keep the startups based in Europe",
    "threadId": "0199a1b2-0000-7000-8000-000000000031"
  }
}

Exemplo de uso (continuar a thread após um administrador confirmar a aceitação no painel):

{
  "name": "firecrawl_agent",
  "arguments": {
    "prompt": "The admin confirmed acceptance of the Apollo terms in the dashboard. Continue.",
    "threadId": "0199a1b2-0000-7000-8000-000000000031",
    "exchange": { "approve": { "approvalId": "0199a1b2-0000-7000-8000-000000000033" } }
  }
}

Retorna:

• ID do job para verificação de status, mais threadId e threadTurn. Use firecrawl_agent_status para fazer polling dos resultados.

9. Verificar Status do Agente (firecrawl_agent_status)

Verifica o status de um job de agente e recupera os resultados quando concluído. Use isto 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 (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 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 fazer scrape e abrir uma página para interação em uma única chamada MCP.
• Passe scrapeId para continuar interagindo com uma página já raspada.
• Para salvar o estado do navegador (cookies, localStorage) em um perfil nomeado, passe url com scrapeOptions: { "profile": { "name": "my-profile", "saveChanges": true } }. O estado é salvo quando firecrawl_interact_stop encerra a sessão.
• Passe exatamente um de url ou scrapeId, mais 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 follow-up ou limpeza.

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

Encerra uma sessão de interação de 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 de pesquisa do MCP.

Abrange: resumos e textos completos de artigos da literatura biomédica, de ciências da vida e clínica (PubMed, bioRxiv, medRxiv), além do arXiv e de outras fontes científicas.

Ferramentas de pesquisa disponíveis:

• firecrawl_research_search_papers: pesquisa metadados e resumos de artigos com uma consulta em linguagem natural, com filtros opcionais de autor, categoria e data.
• firecrawl_research_inspect_paper: recupera metadados canônicos de um ID de artigo (arXiv, PMC, PMID ou DOI).
• firecrawl_research_related_papers: expande a partir de um ou mais artigos âncora por meio do grafo de citações.
• firecrawl_research_read_paper: lê trechos de texto completo de um artigo específico.

Ideal para: fluxos de trabalho de revisão de literatura, busca de artigos e descoberta de repositórios em que o agente precisa de uma superfície de pesquisa focada em vez de uma busca 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 estas ferramentas quando a pergunta for sobre a própria literatura e passe várias formulações distintas da mesma pergunta, pois elas revelam artigos diferentes do que uma única consulta revela.

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.

Ideal para:

• Acompanhar uma página ou algumas páginas ao longo do tempo
• Alertar sobre mudanças significativas usando um objetivo em linguagem simples
• Acompanhar o histórico de verificações e os diffs por página

Padrão de criação recomendado:

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 automaticamente o julgamento de mudanças significativas.

O julgamento de mudanças significativas é executado automaticamente quando goal está definido. Os webhooks de página expõem isMeaningful e judgment em eventos monitor.page.

Escreva objetivos como instruções de monitoramento concisas de 2 a 3 frases. Diga o que deve disparar um alerta, preserve qualquer escopo fornecido pelo usuário 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 requisição, parâmetros de rastreamento, metadados genéricos e elementos de página não relacionados, já é tratado pelo julgador, então não repita isso em todos os objetivos. Se o usuário for vago, mantenha o objetivo amplo; se ele pedir monitoramento amplo ou "qualquer mudança", preserve isso. Se o usuário disser que não se importa com algo, inclua isso explicitamente.

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

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 crawl, 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: lista monitores.
• firecrawl_monitor_get: obtém um monitor.
• firecrawl_monitor_update: atualiza campos, incluindo goal, judgeEnabled, webhook e notification.
• firecrawl_monitor_run: dispara uma verificação agora.
• firecrawl_monitor_delete: exclui um monitor (destrutivo; chame apenas quando o usuário pretender removê-lo).
• firecrawl_monitor_checks: lista verificações, opcionalmente filtradas por status.
• firecrawl_monitor_check: obtém resultados por página, incluindo diff, snapshot, judgment.meaningful e judgment.meaningfulChanges.

14. Ferramenta de Busca para Desenvolvedores (firecrawl_developer_search)

Pesquise um índice criado para agentes de programação. O índice abrange issues do GitHub, pull requests mesclados, READMEs de repositórios e documentação de código.

Ideal 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 de desenvolvimento 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 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 ao lado dos resultados web. Use esta ferramenta em vez disso quando quiser os trechos correspondentes, o filtro skills ou nenhum resultado web na resposta. O endpoint somente de busca expõe ambas as ferramentas, e a mesma escolha se aplica lá.

14b. Ferramenta de Busca no Índice Governamental (firecrawl_gov_search)

Pesquise material jurídico e regulatório primário de fontes governamentais federais, estaduais e locais dos EUA: estatutos, regulamentos, códigos, opiniões judiciais e outras publicações governamentais.

Ideal para: uma pergunta jurídica ou regulatória que precise do texto vigente ou de uma fonte governamental oficial.

Argumentos:

{
  "name": "firecrawl_gov_search",
  "arguments": {
    "query": "excessive force claims against police officers",
    "k": 10,
    "courtType": "federal-appellate",
    "cites": "42 U.S.C. § 1983"
  }
}

• query (obrigatório): a pergunta jurídica ou regulatória ou frase de busca.
• k: número de resultados classificados. O padrão é 10 e o máximo é 100.
• jurisdiction: mantém apenas páginas de uma jurisdição: "us" para federal, ou "us-" mais um código de estado ou território de duas letras, como "us-ca" ou "us-dc".
• court: mantém apenas páginas rotuladas para um tribunal, pelo id de tribunal do CourtListener, como "scotus", "ca9" ou "nysd".
• courtType: mantém apenas páginas de um tipo de tribunal: federal-supreme, federal-appellate, federal-district, federal-bankruptcy, federal-special, military, state-supreme, state-appellate, state-trial, state-special ou state-attorney-general.
• cites: mantém apenas páginas que citam uma lei ou caso, como uma citação impressa, como "42 U.S.C. § 1983" ou "5 U.S. 137", ou um id de citação, como "us:usc:42:1983".
• domain: mantém apenas páginas de um site, como "irs.gov".

Os filtros são opcionais e se combinam: um resultado deve corresponder a todos os filtros definidos. Os filtros mantêm apenas páginas que o índice rotulou, então uma busca filtrada pode deixar de fora páginas relevantes, e nenhum resultado não significa que não exista nenhum. Os rótulos de tribunal são mais completos para tribunais federais e coleções de jurisprudência.

Retorna: Resultados classificados. Cada resultado traz uma posição, um título, uma URL e o trecho correspondente. O endpoint somente de busca também expõe esta ferramenta.

firecrawl_search com categories: ["gov"] pesquisa as mesmas fontes e retorna os resultados em data.web com category: "gov". A categoria gov não aceita esses filtros e não pode ser combinada com outras categorias.

15. Ferramentas Alexandria

O Firecrawl Alexandria é um catálogo de provedores de dados acessíveis por meio da API do Firecrawl com uma chave de API do Firecrawl em uma equipe com acesso ao Alexandria. Sessões sem chave (hospedadas ou locais) recebem Alexandria requires an API key on a team with Alexandria access; as ferramentas de descoberta do Alexandria não são listadas para sessões hospedadas sem chave.

Descoberta semântica (firecrawl_search):

{
  "name": "firecrawl_search",
  "arguments": {
    "query": "podcast conversations about AI agents",
    "sources": ["web", "alexandria"],
    "domainTools": true,
    "limit": 2
  }
}

data.tools usa por padrão sugestões compactas com provedor, capacidade e descrição. Defina toolDetail: "summary" para metadados e navegação, ou toolDetail: "full" para contratos, incluindo entradas, campos de resposta e exemplos. domainTools: true adiciona correspondências contextuais a menções de consulta e URLs de resultado nesse mesmo array. Verifique warning para descoberta indisponível. A busca exige uma consulta e não aceita filtros de navegação do catálogo. Esta descoberta funciona tanto nas superfícies MCP completas quanto nas somente de busca.

Divulgação progressiva (firecrawl_find_tools):

{
  "name": "firecrawl_find_tools",
  "arguments": {
    "providers": ["particle"],
    "capabilities": ["podcasts/episodes/search"],
    "expand": ["options", "response", "examples"],
    "limit": 2
  }
}

Comece sem argumentos para ver categorias e depois estreite progressivamente o catálogo:

Argumentos	Resultado
{}	Categorias e descrições curtas
{"categories":["podcasts"]}	Provedores naquela categoria
{"categories":["podcasts"],"providers":["particle"]}	Nomes e descrições compactos de ferramentas
{"providers":["particle"],"capabilities":["podcasts/episodes/search"]}	Entradas, restrições, resposta e exemplos completos selecionados

Nenhum salto de grupo é necessário. level explícito aceita categories, providers, groups ou tools; expand explícito seleciona seções do contrato. expand: [] mantém os resultados compactos mesmo ao selecionar uma capacidade. Para contratos completos amplos, solicite explicitamente level: "tools" e expand: ["options", "response", "examples"]. As URLs fornecem descoberta contextual sem buscar a página. Os resultados das ferramentas omitem os preços de crédito por capacidade, a menos que includeCosts: true esteja definido; argumentos nextTool de acompanhamento o mantêm.

Os resultados estão em data.alexandria[0].data. Siga o nextTool de um item chamando seu name com seu arguments; o nextTool da página avança a paginação. Objetos next existentes permanecem como chamadas de descoberta do Alexandria utilizáveis por meio de firecrawl_scrape. A descoberta custa zero créditos e nunca executa as ferramentas do provedor. Leia o contrato completo selecionado antes da execução.

Esses controles exigem a implantação correspondente da API do Alexandria.

Executar (firecrawl_scrape com alexandria): passe alexandria em vez de url (exatamente um dos dois; requestId e timeout também podem ser fornecidos). Uma única chamada ou um array de até dez chamadas é aceito.

{
  "name": "firecrawl_scrape",
  "arguments": {
    "alexandria": [
      {
        "provider": "fred",
        "capability": "series/observations",
        "options": { "series_id": "CPIAUCSL" }
      }
    ]
  }
}

Retorna: { success, scrape_id, requestId, data: { alexandria: [...], creditsCost } }. Cada item é um resultado (provider, capability, data, records, upstreamStatus) ou um error com um code; o lote nunca falha como um todo por causa de um erro de provedor e data.creditsCost é o total cobrado pela solicitação. Os corpos de erro do Alexandria (403 sem acesso ao Alexandria e status de cobrança 402/409) são repassados em banda com seu code.

A execução gera um x-request-id e o retorna em caso de sucesso ou falha. Repita o payload idêntico com esse requestId; não crie um novo ID após um resultado incerto. Os créditos disponíveis são verificados pela API.

Um provedor do Alexandria cujos termos a equipe não aceitou falha antes de qualquer execução com HTTP 403 e este corpo:

{
  "success": false,
  "code": "THIRD_PARTY_DATA_TERMS_REQUIRED",
  "error": "An organization admin must accept the benzinga provider's terms (version 2026-09-12-placeholder) before this request can run. Accept them at https://www.firecrawl.dev/app/alexandria/benzinga",
  "requiresAction": {
    "type": "accept_terms",
    "terms": "benzinga",
    "version": "2026-09-12-placeholder",
    "url": "https://www.firecrawl.dev/app/alexandria/benzinga"
  }
}

O resultado da ferramenta o repassa como um erro com structuredContent contendo code, status: 403, requestId, o objeto requiresAction inalterado e next_actions (human_action_required e depois retry_same_request). Aceitar termos é um ato legal, então um administrador da organização os aceita no painel do Firecrawl, não por meio do MCP. Use a chamada nextTool retornada para ler o acordo por meio de firecrawl_scrape com alexandria: [{provider: "firecrawl", capability: "terms/show", options: {provider: "<provider>"}}], enviada separadamente da execução do provedor, e apresente-o ao usuário. Um administrador da organização então o aceita em requiresAction.url, ou em https://www.firecrawl.dev/app/settings?tab=data-sources. firecrawl_scrape recusa todas as outras capacidades de terms/*, então não faz alterações na conta. Uma solicitação de dados não é consentimento, e nenhuma aceitação automática ou repetição incerta ocorre. Nenhum crédito é cobrado pela recuperação bloqueada. Depois que o administrador confirmar a aceitação, chame a mesma ferramenta novamente com o payload idêntico e requestId.

16. Ferramenta de Uso de Créditos

A ferramenta exige uma conta autenticada do Firecrawl e é somente leitura.

• firecrawl_credit_usage tem como padrão { "view": "current" } e retorna remainingCredits, planCredits, billingPeriodStart e billingPeriodEnd. Os créditos restantes podem exceder os créditos do plano quando a equipe tem recargas ou concessões.
• Passe { "view": "historical" } para períodos de mês calendário contendo startDate, endDate e creditsUsed. Passar { "byApiKey": true } também seleciona a visão histórica e divide os períodos por chave de API; cada linha então inclui apiKey. Passar { "byEndpoint": true } em vez disso divide os períodos pelo endpoint que usou os créditos (scrape, search, crawl, map, agent, ...); cada linha então inclui endpoint. Passe { "bin": "day" } para um período por dia UTC em vez de por mês calendário. Não combine byApiKey com byEndpoint, nem qualquer um destes com { "view": "current" }. O endDate do período mais recente pode ser nulo. Se a API do Firecrawl ainda não oferecer a divisão por endpoint ou períodos diários, o resultado traz um notice e números mensais.

Uso programático (instável)

O pacote também expõe um ponto de entrada de biblioteca para incorporar o servidor em outro runtime. Ele é instável: a API, suas opções e seus tipos podem mudar em qualquer versão, incluindo versões menores e de correção, então fixe uma versão exata.

npm install --save-exact firecrawl-mcp zod

O exemplo define parâmetros de ferramenta com zod, então o projeto de incorporação o instala como dependência própria.

import { createFirecrawlMcpServer } from 'firecrawl-mcp/server';
import { z } from 'zod';

const server = createFirecrawlMcpServer({
  transport: 'httpStream',
  apiKey: process.env.FIRECRAWL_API_KEY,
  unstable_hooks: {
    registerExtraTools: (registrar) => {
      registrar.addTool({
        name: 'my_tool',
        description: 'An extra tool served next to the Firecrawl tools.',
        parameters: z.object({ text: z.string() }),
        execute: async ({ text }) => text,
      });
    },
  },
});

await server.start({
  transportType: 'httpStream',
  httpStream: { port: 3000, host: '127.0.0.1', endpoint: '/mcp', stateless: true },
});
// MCP endpoint: http://127.0.0.1:3000/mcp

Defina host explicitamente. Sem isso, o servidor escuta em localhost, que o Node vincula a um único endereço (frequentemente apenas ::1), então requisições para 127.0.0.1 são recusadas. Use 0.0.0.0 ou :: para aceitar conexões de outras máquinas apenas atrás de controles de acesso de rede ou de uma verificação de unstable_hooks.authenticate: sem uma, todo chamador que conseguir alcançar a porta é atendido com o apiKey configurado.

A biblioteca não verifica Host nem Origin a menos que solicitado, e seus cabeçalhos CORS permitem qualquer origem. Um servidor acessível a partir de um navegador na mesma máquina deve passar httpStream.allowedHosts (por exemplo, ['localhost', '127.0.0.1', '[::1]']): requisições cujo cabeçalho Host ou Origin nomeie outro host então recebem 403 (exceto GET e HEAD no caminho de health), e os cabeçalhos CORS ecoam a origem permitida. A linha de comando define esta lista no modo HTTP local.

As opções espelham as variáveis de ambiente da CLI: apiUrl, apiKey, transport, logging, safeMode, fileAccess (local ou upload), requireCredential, searchFeedback e endpointFeedback. unstable_hooks aceita:

Hook	Propósito
authenticate(request)	Resolve a sessão para uma requisição; lance um Response para rejeitá-la.
wrapTool(tool)	Decora cada ferramenta registrada.
onToolResult(event)	Observa o início e o resultado de cada chamada de ferramenta.
instructions	Instruções do servidor, ou uma função que escolhe entre os padrões.
registerExtraTools(registrar, context)	Adiciona ferramentas após as integradas.
outboundRequest(session)	Credencial e cabeçalhos extras para cada requisição à API do Firecrawl.
beforeKeylessRequest(session, origin)	Recusa uma requisição sem chave lançando uma exceção.
toolFilter(name)	Deixa ferramentas integradas fora da instância.
configureHttp(app)	Adiciona rotas HTTP.
oauth.protectedResource	Serve metadados de recurso protegido OAuth.

O servidor é construído sobre o SDK oficial TypeScript do MCP (@modelcontextprotocol/server). Use os tipos exportados de firecrawl-mcp/server (Session, ToolDefinition, ToolRegistrar, FirecrawlMcpServerHooks e outros) em vez dos do próprio SDK.

O ponto de entrada também exporta os auxiliares que as ferramentas integradas usam, como recoveryPayload, normalizeHeader, requestOrigin, isRuntimeUserAgent, initializeClientSlug, searchToolBaseFields, searchOutputSchema e structuredCompact, para que ferramentas e hooks extras possam corresponder ao comportamento integrado. Eles também são instáveis.

Sistema de Logs

O servidor inclui logging abrangente:

• Status e progresso das operações
• Métricas de desempenho
• Rastreamento de limite de taxa
• Condições de erro

Exemplos de mensagens de log:

[INFO] Firecrawl MCP Server initialized successfully
[INFO] Starting scrape for URL: https://example.com
[ERROR] Rate limit exceeded

Tratamento de Erros

O servidor oferece tratamento de erros robusto:

• Erros de limite de taxa da API expostos 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 feature
3. Execute os testes: npm test
4. Envie um pull request

Agradecimentos aos contribuidores

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

Agradecimentos 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 detalhes

Dados estruturados e resultados grandes

A busca autenticada usa por padrão resultados web, ferramentas semânticas Alexandria e correspondências de domínio. Comece com a pergunta real. Use firecrawl_find_tools para busca direta de ferramentas semânticas, contratos selecionados ou navegação progressiva: categorias → provedores → ferramentas compactas → contrato selecionado. Execute ferramentas por meio de firecrawl_scrape; scraping de URL comum e busca nunca executam automaticamente ferramentas de provedor.

Para contratos selecionados, prefira expand: ["options", "response"] e solicite exemplos apenas se a forma da entrada não estiver clara. Inspecione capacidades relacionadas em conjunto e reutilize os contratos retornados.

Para um resultado de workflow potencialmente grande, forneça e preserve um requestId de nível superior antes da execução. Esse ID permanece disponível mesmo que o cliente rejeite a resposta. Scrapes de URL comuns usam o ID de scrape retornado em vez disso.

Para um resultado grande de workflow retido ou de scrape comum, chame firecrawl_scrape com:

{
  "alexandria": {
    "provider": "firecrawl",
    "capability": "bash",
    "options": {
      "requestId": "<source-request-or-scrape-id>",
      "command": "ls -lh"
    }
  }
}

Leia stdout, stderr, exitCode e workspaceId em data.alexandria[0].data. Continue com options: {workspaceId, command} para inspecionar response.json usando jq, ou document.md usando comandos de texto limitados para scrapes comuns. Mantenha a saída seletiva. O carregamento de fonte deve ser uma chamada autônoma; seu ID de fonte aninhado difere do ID de requisição de execução de nível superior. Workspaces expiram após cinco minutos ociosos, e nem todo resultado é retido (incluindo ZDR e payloads de workflow de provedores de API). IDs de busca não são suportados.

Para fontes de workflow, response.json preserva o envelope da API: selecione .data.alexandria[].data, depois o response.key do contrato selecionado quando não vazio. Combine contagens e projeções relacionadas em um único comando Bash quando essa forma for conhecida, em vez de inspecionar chaves repetidamente.

Respostas de execução Alexandria bem-sucedidas acima de 20.000 tokens estimados (bytes UTF-8 serializados divididos por quatro) retornam um pequeno handoff após o Bash remoto confirmar que o lote completo está acessível. Siga nextTool para inspecionar os dados retidos. Isso adiciona uma chamada Bash e inicia um workspace com TTL ocioso de cinco minutos. O payload completo é preservado. Se a confirmação falhar, a resposta original permanece inline. Busca, scrape de URL comum, respostas de erro e chamadas utilitárias do Firecrawl permanecem inalteradas. Esse orçamento de entrega não mede o contexto restante do cliente; nenhum cache de resultado local ao processo é adicionado. Quando ferramentas de sistema de arquivos locais estiverem disponíveis, salvar a saída da CLI e ler seções selecionadas é outra opção.

A sequência de descoberta da CLI mapeia para estas chamadas MCP:

Intenção	Ferramenta	Argumentos
Ferramentas web + semânticas + de domínio	firecrawl_search	{"query":"<user question>"}
Apenas ferramentas semânticas	firecrawl_search	{"query":"<user question>","sources":["alexandria"]}
Categorias	firecrawl_find_tools	{}
Provedores em uma categoria	firecrawl_find_tools	{"categories":["<category-id>"]}
Ferramentas compactas de provedor	firecrawl_find_tools	{"providers":["<provider-id>"]}
Contrato selecionado	firecrawl_find_tools	{"providers":["<provider-id>"],"capabilities":["<capability-id>"]}
Executar	firecrawl_scrape	{"alexandria":{"provider":"<provider-id>","capability":"<capability-id>","options":{"<required-field>":"<value>"}}}

Find Tools e execução estão disponíveis tanto na superfície completa quanto na superfície de busca. Reutilize um contrato completo da busca quando presente, em vez de fazer outra chamada de descoberta. Siga a navegação nextTool retornada apenas quando mais resultados forem necessários.

Feedback de sessão Alexandria

A ferramenta firecrawl_feedback existente aceita endpoint: "alexandria":

{
  "endpoint": "alexandria",
  "rating": "partial",
  "requestedWebsite": {
    "url": "https://example.com",
    "requestedFunctionality": "Find records and download their attachments"
  },
  "objective": "Compare contract requirements across agencies before bidding",
  "rationale": "Found summaries but could not retrieve attachments"
}

O objective opcional é o objetivo subjacente da sessão: o que o agente ou seu usuário estava tentando realizar, além do único site em requestedWebsite.

Isso usa POST /v2/feedback autenticado, sem um ID de job. Deve chegar dentro de 20 minutos da busca, descoberta ou execução Alexandria mais recente da equipe; feedback posterior é rejeitado com FEEDBACK_WINDOW_EXPIRED. Feedback elegível pode reembolsar 1 crédito, sujeito a limites diários de 10 créditos por site e 100 créditos por equipe (dia UTC). Após qualquer um dos limites, o feedback ainda é registrado sem reembolso, e a resposta define websiteCapReached ou dailyCapReached. Arrays opcionais providerFeedback e capabilityFeedback descrevem lacunas de cobertura e problemas de execução; o schema da ferramenta lista os valores de problema suportados. Um new_capability_request exige requestedFunctionality; missing_capability (o provedor existe mas não tem a capacidade) não exige. Os controles existentes de opt-out de feedback e de autenticação se aplicam.

Resultados elegíveis de execução e descoberta Alexandria incluem um ponteiro feedbackTool com o nome da ferramenta e um esqueleto dos argumentos. O ponteiro é omitido para chamadas internas do Firecrawl, como bash, e quando firecrawl_feedback não está registrado (FIRECRAWL_NO_ENDPOINT_FEEDBACK ou inicialização sem chave).