Firecrawl MCP

Firecrawl MCP Server

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

Agradecimentos especiais ao @vrknetha e @knacklabs pela implementação inicial!

Recursos

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

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

Instalação

MCP hospedado (tier gratuito sem chave)

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

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

No tier gratuito sem chave, scrape, search e parse funcionam sem chave de API (com limitação de taxa). Outras ferramentas como crawl, map e agent ainda exigem uma chave.

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

Para uma conexão interativa de conta, configure seu cliente MCP para usar esta URL de servidor. Este é um endpoint MCP, não uma página de navegador; use o fluxo de conexão de conta do cliente e não adicione uma segunda entrada do 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 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 para agentes para instruções específicas de cada cliente.

Endpoint somente de pesquisa

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

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

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

Executando com npx

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

Instalação manual

npm install -g firecrawl-mcp

Executando no Cursor

Configurando o Cursor 🖥️ Observação: requer a versão 0.45.6+ do Cursor 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 estiver enfrentando problemas, tente cmd /c "set FIRECRAWL_API_KEY=your-api-key && npx -y firecrawl-mcp"

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

Após adicionar, atualize a lista de servidores MCP para ver as novas ferramentas. O Composer Agent usará automaticamente o Firecrawl MCP quando apropriado, mas você pode solicitá-lo explicitamente descrevendo suas necessidades de extração web. Acesse o Composer via Command+L (Mac), selecione "Agent" 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 Streamable HTTP em modo local

Para executar o servidor usando Streamable HTTP localmente em vez do transporte padrão stdio:

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

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

Instalação via Smithery (Legado)

Para instalar o Firecrawl para Claude Desktop automaticamente via Smithery:

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

Executando no VS Code

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

Para instalação manual, adicione o seguinte bloco JSON ao arquivo 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 no seu workspace. Isso permitirá que você compartilhe a configuração com outras pessoas:

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

Configuração

Variáveis de Ambiente

Necessárias para a API 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 access tokens OAuth (fco_…) por meio do servidor de autorização em firecrawl.dev. Este servidor MCP encaminha qualquer credencial que ele resolver para a API do Firecrawl como Authorization: Bearer ….

• Transports 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 access tokens (fco_…). Os refresh tokens (fcr_…) devem ser trocados no endpoint de token, não passados para a API de scrape/search.

Superfície somente de pesquisa (hospedada)

No modo hospedado (CLOUD_SERVICE=true), uma segunda instância no mesmo processo atende o endpoint somente de pesquisa. O serviço empacotado 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) é o interruptor operacional suportado; defina-o como false para impedir que a instância de pesquisa inicie. O processo Node também aceita FIRECRAWL_MCP_SEARCH_PORT, FIRECRAWL_MCP_SEARCH_ENDPOINT e FIRECRAWL_MCP_SEARCH_RESOURCE_URL para testes isolados. Essas substituições não reconfiguram as rotas do nginx empacotado 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 informações na web: 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, ciências da vida, clínica ou arXiv): use research tools — eles pesquisam resumos e textos completos de artigos. search com categories: ["research"] é uma coisa diferente: um filtro de site sobre resultados de pesquisa comuns na web.
• Se você precisar de pesquisa complexa em várias fontes desconhecidas: use agent
• Se você quiser analisar um site inteiro ou uma seção: use crawl (com limites!)
• Se você precisar de automação interativa do navegador (clicar, digitar, navegar): use interact com uma URL para uma página nova, ou scrape + interact quando você já tiver extraído a página ou precisar de um controle mais preciso da extração

Tabela de Referência Rápida

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

Guia de Seleção de Formato

Ao usar scrape, escolha o formato certo:

• Formato JSON (recomendado para a maioria dos casos): Use quando você 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 de janela de 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 resumo ou analisar a estrutura da página.

Ferramentas Disponíveis

1. Ferramenta de Scrape (firecrawl_scrape)

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

Melhor para:

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

Não recomendado para:

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

Erros comuns:

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

Escolhendo o formato certo:

• Formato JSON (preferido): Para a maioria dos casos de uso, use o formato JSON com um schema para extrair apenas os dados específicos necessários. Isso mantém as respostas focadas e evita estouro de janela de contexto.
• Formato Markdown: Somente quando a tarefa realmente exigir o conteúdo completo da página (por exemplo, resumir um artigo inteiro, analisar a estrutura da página).

Exemplo de prompt:

"Obtenha os detalhes do produto 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 de branding - extrair identidade da marca):

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

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

Retorna:

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

2. Ferramenta de Mapa (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 todos os URLs de example.com."

Exemplo de uso:

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

Retorna:

• Matriz de URLs encontrados no site

3. Ferramenta de Pesquisa (firecrawl_search)

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

Melhor para:

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

Não recomendado para:

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

Erros comuns:

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

Exemplo de uso:

{
  "name": "firecrawl_search",
  "arguments": {
    "query": "remote work stipend policies at tech companies",
    "highlights": true,
    "limit": 5,
    "lang": "en",
    "country": "us",
    "scrapeOptions": {
      "formats": ["markdown"],
      "onlyMainContent": true,
      "redactPII": true
    }
  }
}

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

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

Retorna:

• Matriz de resultados de pesquisa (com conteúdo raspado opcional), além de um campo id. Passe esse id para firecrawl_search_feedback depois de usar os resultados para reembolsar 1 crédito (a pesquisa custa 2) e melhorar a qualidade da busca.

Exemplo de prompt:

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

3b. Ferramenta de Feedback de Pesquisa (firecrawl_search_feedback)

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

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

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

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

Limite diário de reembolso (por equipe, por dia UTC, padrão 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 via /v2/feedback. Use isso para feedback em nível de endpoint em trabalhos de scrape, parse, map ou search. Para qualidade de resultados de pesquisa especificamente, prefira firecrawl_search_feedback, pois inclui orientações específicas de pesquisa.

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

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, consulta até atingir um estado terminal e retorna o status/dados finais do crawl.

Melhor para:

• Extrair conteúdo de várias páginas relacionadas, quando você precisa de cobertura abrangente.

Não recomendado para:

• Extrair conteúdo de uma única página (use scrape)
• Quando os limites de tokens são uma preocupação (use map + scrape para controle mais rigoroso)
• Quando você precisa de resultados rápidos (o crawl pode ser lento)

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

Erros comuns:

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

Exemplo de prompt:

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

Exemplo de uso:

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

Retorna:

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

5. Verificar Status do Crawl (firecrawl_check_crawl_status)

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

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

Retorna:

• A resposta inclui o status do trabalho de crawl:

6. Ferramenta de Parse (firecrawl_parse)

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

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

Não recomendado para: URLs remotos (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.

Fluxo do MCP hospedado: O MCP hospedado não pode ler o sistema de arquivos do chamador diretamente. Chame firecrawl_parse com filePath para receber um comando de upload de curta duração e nextToolCall, faça o upload do arquivo localmente e depois chame firecrawl_parse novamente com o uploadRef retornado. A criação da URL de upload hospedada requer autenticação do 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 comum apenas com chave de API de nuvem não pode 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"]
      }
    }
  }
}

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

8. Ferramenta Agent (firecrawl_agent)

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

Como funciona:

O agente realiza buscas na web, segue links, lê páginas e coleta dados de forma autônoma. Isso funciona assincronamente - ele retorna um ID de trabalho imediatamente, e você consulta 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 ID do trabalho
2. Faça outro trabalho enquanto o agente pesquisa (pode levar minutos para consultas complexas)
3. Consulte firecrawl_agent_status com o ID do trabalho para verificar o progresso
4. Quando o status for "completed", a resposta inclui os dados extraídos

Melhor para:

• Tarefas de pesquisa complexas onde você não sabe os URLs exatos
• Coleta de dados de múltiplas fontes
• Encontrar informações dispersas na web
• Tarefas onde você pode fazer outro trabalho enquanto espera pelos resultados

Não recomendado para:

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

Argumentos:

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

Exemplo de prompt:

"Encontre os fundadores do Firecrawl e suas origens"

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

{
  "name": "firecrawl_agent",
  "arguments": {
    "prompt": "Find the top 5 AI startups founded in 2024 and their funding amounts",
    "schema": {
      "type": "object",
      "properties": {
        "startups": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": { "type": "string" },
              "funding": { "type": "string" },
              "founded": { "type": "string" }
            }
          }
        }
      }
    }
  }
}

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

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

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

Retorna:

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

9. Verificar Status do Agent (firecrawl_agent_status)

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

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

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

Status possíveis:

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

10. Ferramenta Interact (firecrawl_interact)

Interaja com um URL novo 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, para o modo URL, o scrapeId derivado para acompanhamento ou limpeza.

11. Ferramenta Stop Interact (firecrawl_interact_stop)

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

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

12. Ferramentas de Pesquisa (firecrawl_research_*)

Pesquise e inspecione artigos e repositórios GitHub através das ferramentas MCP de pesquisa.

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

Ferramentas de pesquisa disponíveis:

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

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

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

13. Ferramentas de Monitoramento (firecrawl_monitor_*)

Crie e gerencie monitores de página recorrentes. Os monitores executam raspagens ou crawls agendados, comparam cada resultado com o último snapshot retido e podem notificar por webhook ou e-mail.

Melhor para:

• Observar uma página ou algumas páginas ao longo do tempo
• Alertar sobre mudanças significativas usando um objetivo em linguagem simples
• Rastrear 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 constrói a solicitação de monitoramento com um agendamento de 30 minutos e a API habilita a avaliação de mudanças significativas automaticamente.

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

Escreva metas como instruções concisas de monitoramento de 2 a 3 frases. Diga o que deve acionar um alerta, preserve qualquer escopo que o usuário tenha fornecido e inclua exclusões específicas de intenção somente quando forem óbvias a partir da solicitação. Ruído genérico, como espaços em branco, alterações somente 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 o repita em cada meta. Se o usuário for vago, mantenha a meta ampla; se ele pedir monitoramento amplo ou "qualquer alteração", preserve isso. Se o usuário disser que não se importa com algo, inclua isso explicitamente.

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

Múltiplas páginas com webhooks:

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

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

Passe body quando você precisar de alvos de rastreamento, rastreamento de alterações 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: aciona uma verificação agora.
• firecrawl_monitor_delete: exclui um monitor (destrutivo; chame somente quando o usuário pretender removê-lo).
• firecrawl_monitor_checks: lista verificações, opcionalmente filtradas por status.
• firecrawl_monitor_check: obtém resultados em nível de página, incluindo diff, snapshot, judgment.meaningful e judgment.meaningfulChanges.

14. Ferramenta de busca para desenvolvedores (firecrawl_developer_search)

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

Melhor para: uma pergunta sobre 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 busca do desenvolvedor.
• k: número de resultados classificados. O padrão é 10 e o máximo é 100.
• skills: defina como "only" para buscar somente em arquivos de habilidades do agente.

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

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

Sistema de Logging

O servidor inclui logging abrangente:

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

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 fornece tratamento robusto de erros:

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

Exemplo de resposta de erro:

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

Desenvolvimento

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

Contribuindo

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

Agradecimentos aos contribuidores

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

Agradecemos ao MCP.so e à Klavis AI por hospedarem e a @gstarwd, @xiangkaiz e @zihaolin96 por integrarem nosso servidor.

Licença

Licença MIT - consulte o arquivo LICENSE para detalhes