Firecrawl

Servidor MCP Firecrawl

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

Um grande obrigado a @vrknetha, @knacklabs pela implementação inicial!

Funcionalidades

• Pesquisar na web e obter o conteúdo completo da página
• Extrair qualquer URL em dados limpos e estruturados
• Interagir com páginas — clicar, navegar e operar
• Pesquisa aprofundada com agente autônomo
• Novas tentativas automáticas e limitação de taxa
• Suporte à nuvem e auto-hospedado
• Suporte a SSE

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

Instalação

MCP Hospedado (camada gratuita sem chave)

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

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

Na camada gratuita sem chave, scrape, search e interact funcionam sem uma chave de API (limitados por taxa). Outras ferramentas como crawl, map, agent e extract ainda precisam de uma chave.

Prefira uma chave de API ou OAuth sempre que o humano puder se inscrever. Isso desbloqueia o conjunto completo de ferramentas e limites mais altos. Com uma chave, use:

https://mcp.firecrawl.dev/{FIRECRAWL_API_KEY}/v2/mcp

Consulte a documentação do servidor MCP e o guia de integração do agente para detalhes de configuração.

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ágina e tem sua própria identidade OAuth; o endpoint completo acima permanece inalterado. Consulte docs/search-profile.md para o contrato completo.

Executando com npx

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

Instalação Manual

npm install -g firecrawl-mcp

Executando no Cursor

Configurando o Cursor 🖥️ Nota: Requer Cursor versão 0.45.6+ Para obter as instruções de configuração mais atualizadas, consulte a documentação oficial do Cursor sobre como configurar servidores MCP: Guia de Configuração do Servidor MCP do Cursor

Para configurar o Firecrawl MCP no Cursor v0.48.6

1. Abra as Configurações do Cursor
2. Vá para Funcionalidades > Servidores MCP
3. Clique em "+ Adicionar novo servidor MCP global"
4. Insira o seguinte código:

   {
     "mcpServers": {
       "firecrawl-mcp": {
         "command": "npx",
         "args": ["-y", "firecrawl-mcp"],
         "env": {
           "FIRECRAWL_API_KEY": "YOUR-API-KEY"
         }
       }
     }
   }
   

Para configurar o Firecrawl MCP no Cursor v0.45.6

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

Para executar o servidor usando HTTP Transmissível localmente em vez do transporte stdio padrão:

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

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

Instalando via Smithery (Legado)

Para instalar o Firecrawl para Claude Desktop automaticamente via Smithery:

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

Executando no VS Code

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

Para instalação manual, adicione o seguinte bloco JSON ao seu arquivo de Configurações do Usuário (JSON) no VS Code. Você pode fazer isso pressionando Ctrl + Shift + P e digitando Preferences: Open User Settings (JSON).

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

Opcionalmente, você pode adicioná-lo a um arquivo chamado .vscode/mcp.json no seu espaço de trabalho. Isso permitirá que você compartilhe a configuração com outras pessoas:

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

Configuração

Variáveis de Ambiente

Necessário para API na Nuvem

• FIRECRAWL_API_KEY: Sua chave de API Firecrawl
  • Necessário ao usar a API na nuvem (padrão)
  • Opcional ao usar instância auto-hospedada com FIRECRAWL_API_URL
• FIRECRAWL_API_URL (Opcional): Endpoint de API personalizado para instâncias auto-hospedadas
  • Exemplo: https://firecrawl.your-domain.com
  • Se não fornecido, a API na nuvem será usada (requer chave de API)

MCP OAuth (Tokens de acesso Bearer)

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

• Transportes de fluxo HTTP (CLOUD_SERVICE=true, HTTP_STREAMABLE_SERVER=true ou SSE_LOCAL=true): Os clientes devem enviar Authorization: Bearer <fco_access_token> nas 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 extração/pesquisa.

Superfície somente de pesquisa (hospedada)

No modo hospedado (CLOUD_SERVICE=true), uma segunda instância em processo serve 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 OAuth é https://mcp.firecrawl.dev/v2/mcp-search.

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

A instância de pesquisa requer autenticação para cada requisiçã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ê sabe a URL exata que deseja: use scrape (com formato JSON para dados estruturados)
• Se você tem várias URLs conhecidas: chame scrape para cada URL. Se você precisar especificamente de uma operação de API em lote, use o endpoint em lote da API Firecrawl fora do MCP.
• Se você precisa descobrir URLs em um site: use map
• Se você quer pesquisar informações na web: use search
• Se você precisa de pesquisa complexa em várias fontes desconhecidas: use agent
• Se você quer analisar um site inteiro ou seção: use crawl (com limites!)
• Se você precisa de automação de navegador interativa (clicar, digitar, navegar): use interact com uma URL para uma página nova, ou scrape + interact quando você já extraiu a página ou precisa de controle de extração mais rigoroso

Tabela de Referência Rápida

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

Guia de Seleção de Formato

Ao usar scrape, escolha o formato certo:

• Formato JSON (recomendado para a maioria dos casos): Use quando precisar de dados específicos de uma página. Defina um esquema 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 precisa do conteúdo completo da página, como ler um artigo inteiro para sumarização ou analisar a estrutura da página.

Ferramentas Disponíveis

1. Ferramenta Scrape (firecrawl_scrape)

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

Melhor para:

• Extração de conteúdo de página única, 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 scrape repetidas para URLs conhecidas, ou map + scrape para descobrir URLs primeiro, ou crawl para conteúdo completo da página)
• 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 chamada scrape. Chame scrape uma vez por URL no MCP. Se você precisar especificamente de uma operação de API em lote, use o endpoint em lote da API Firecrawl fora do MCP.
• Usar formato markdown por padrão (use formato JSON para extrair apenas o que você precisa).

Escolhendo o formato certo:

• Formato JSON (preferencial): Para a maioria dos casos de uso, use o formato JSON com um esquema 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 (ex.: sumarizar um artigo inteiro, analisar a estrutura da página).

Exemplo de Prompt:

"Obtenha os detalhes do produto de https://example.com/product."

Exemplo de Uso (formato JSON - preferencial):

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

Exemplo de Uso (formato markdown - quando o conteúdo completo é necessário):

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

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

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

Formato Branding: Extrai identidade de marca abrangente (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 de identificação pessoal redigidas.

Retorna:

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

2. Ferramenta Map (firecrawl_map)

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

Melhor para:

• Descobrir URLs em um site antes de decidir o que extrair
• Encontrar seções específicas de um site

Não recomendado para:

• Quando você já sabe qual URL específica precisa (use scrape)
• Quando você precisa do conteúdo das páginas (use scrape após o mapeamento)

Erros comuns:

• Usar crawl para descobrir URLs em vez de map

Exemplo de Prompt:

"Liste todas as URLs em example.com."

Exemplo de Uso:

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

Retorna:

• Array de URLs encontradas no site

3. Ferramenta Search (firecrawl_search)

Pesquisa na web e, opcionalmente, extrai conteúdo dos resultados da pesquisa.

Melhor para:

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

Não recomendado para:

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

Erros comuns:

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

Exemplo de Uso:

{
  "name": "firecrawl_search",
  "arguments": {
    "query": "latest AI research papers 2023",
    "highlights": true,
    "limit": 5,
    "lang": "en",
    "country": "us",
    "scrapeOptions": {
      "formats": ["markdown"],
      "onlyMainContent": true,
      "redactPII": true
    }
  }
}

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

Retorna:

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

Exemplo de Prompt:

"Encontre os artigos de pesquisa mais recentes sobre IA publicados em 2023."

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 de 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 um bom feedback.

Desativação: 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 desabilitar 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 conteúdos específicos que o agente esperava encontrar, mas não encontrou. Uma entrada por tópico ausente — estes são agregados entre equipes e nos dizem o que indexar em seguida.

Limite diário de reembolso (por equipe, por dia UTC, padrão 100 créditos). Quando o creditsRefundedToday de uma equipe atinge dailyRefundCap, envios subsequentes ainda registram o 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 job de endpoint v2 concluído através de /v2/feedback. Use isto para feedback em nível de endpoint em jobs de scrape, parse, map ou search. Para qualidade de resultado de busca especificamente, prefira firecrawl_search_feedback porque inclui orientação específica de busca.

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

Desativação: 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 { success, feedbackId, creditsRefunded, creditsRefundedToday?, dailyRefundCap?, dailyCapReached?, alreadySubmitted?, warning? }.

4. Ferramenta de Rastreamento (firecrawl_crawl)

Inicia um job de rastreamento, pesquisa até atingir um estado terminal e retorna o status/dados finais do rastreamento.

Ideal 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 raspagem)
• Quando limites de token são uma preocupação (use map + scrape para controle mais rigoroso)
• Quando você precisa de resultados rápidos (o rastreamento pode ser lento)

Aviso: Respostas de rastreamento podem ser muito grandes e podem exceder os limites de token. Limite a profundidade do rastreamento 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 token)
• Usar rastreamento para uma única página (use raspagem em vez disso)

Exemplo de Prompt:

"Obtenha todos os posts do blog dos dois primeiros níveis de exemplo.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 rastreamento após pesquisa interna, incluindo id, status, completed, total, creditsUsed, expiresAt, next e data. Use o id retornado com firecrawl_check_crawl_status se precisar verificar novamente o job mais tarde.

5. Verificar Status do Rastreamento (firecrawl_check_crawl_status)

Verifique o status e os resultados de um job de rastreamento existente pelo ID.

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

Retorna:

• A resposta inclui o status do job de rastreamento:

6. Ferramenta de Análise (firecrawl_parse)

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

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

Não recomendado para: URLs remotas (use raspagem), múltiplos arquivos em uma chamada (chame parse uma vez por arquivo) ou ações apenas no navegador, como capturas de tela e cliques.

Fluxo 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, em seguida, chame firecrawl_parse novamente com o uploadRef retornado. Criar a URL de upload hospedada requer autenticação Firecrawl ou elegibilidade keyless. No modo npx firecrawl-mcp local, a análise direta de arquivos atualmente requer FIRECRAWL_API_URL apontando para uma API Firecrawl auto-hospedada; um servidor local simples com apenas chave de API na nuvem não pode ler e fazer upload de arquivos através desta ferramenta.

Exemplo de Uso:

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

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

7. Ferramenta de Extração (firecrawl_extract)

Extraia informações estruturadas de páginas da web usando capacidades de LLM. Suporta tanto IA na nuvem quanto extração LLM auto-hospedada.

Ideal para:

• Extrair dados estruturados específicos como preços, nomes, detalhes.

Não recomendado para:

• Quando você precisa do conteúdo completo de uma página (use raspagem)
• Quando você não está procurando dados estruturados específicos

Argumentos:

• urls: Array de URLs das quais extrair informações
• prompt: Prompt personalizado para a extração LLM
• systemPrompt: Prompt do sistema para guiar o LLM
• schema: Esquema JSON para extração de dados estruturados
• allowExternalLinks: Permitir extração de links externos
• enableWebSearch: Habilitar busca na web para contexto adicional
• includeSubdomains: Incluir subdomínios na extração

Ao usar uma instância auto-hospedada, a extração usará seu LLM configurado. Para API na nuvem, usa o serviço LLM gerenciado do Firecrawl. Exemplo de Prompt:

"Extraia o nome do produto, preço e descrição destas páginas de produto."

Exemplo de Uso:

{
  "name": "firecrawl_extract",
  "arguments": {
    "urls": ["https://example.com/page1", "https://example.com/page2"],
    "prompt": "Extract product information including name, price, and description",
    "systemPrompt": "You are a helpful assistant that extracts product information",
    "schema": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "price": { "type": "number" },
        "description": { "type": "string" }
      },
      "required": ["name", "price"]
    },
    "allowExternalLinks": false,
    "enableWebSearch": false,
    "includeSubdomains": false
  }
}

Retorna:

• Dados estruturados extraídos conforme definido pelo seu esquema

{
  "content": [
    {
      "type": "text",
      "text": {
        "name": "Example Product",
        "price": 99.99,
        "description": "This is an example product description"
      }
    }
  ],
  "isError": false
}

8. Ferramenta de Agente (firecrawl_agent)

Agente de pesquisa web autônomo. Esta é uma camada de agente de IA separada que navega independentemente na 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 é executado de forma assíncrona - retorna um ID de job imediatamente, e você consulta firecrawl_agent_status para verificar quando estiver completo e recuperar os resultados.

Fluxo de trabalho 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. Consulte 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

Ideal para:

• Tarefas de pesquisa complexas onde você não conhece as URLs exatas
• Coleta de dados de múltiplas fontes
• Encontrar informações espalhadas pela web
• Tarefas onde você pode fazer outro trabalho enquanto espera pelos resultados

Não recomendado para:

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

Argumentos:

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

Exemplo de Prompt:

"Encontre os fundadores do Firecrawl e suas formações"

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

Depois consulte com firecrawl_agent_status usando o ID do job 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 job para verificação de status. Use firecrawl_agent_status para consultar os resultados.

9. Verificar Status do Agente (firecrawl_agent_status)

Verifique o status de um job de agente e recupere os resultados quando estiver completo. Use isto 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: 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.

Ideal 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 chamada MCP.
• Passe scrapeId para continuar interagindo com uma página raspada existente.
• 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, para o modo URL, o scrapeId derivado para acompanhamento ou limpeza.

11. Ferramenta Parar Interação (firecrawl_interact_stop)

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

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

12. Ferramentas de Pesquisa (firecrawl_research_*)

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

Ferramentas de pesquisa disponíveis:

• firecrawl_research_search_papers: pesquisar artigos de pesquisa.
• firecrawl_research_inspect_paper: inspecionar um artigo.
• firecrawl_research_related_papers: encontrar artigos relacionados.
• firecrawl_research_read_paper: ler conteúdo do artigo.
• firecrawl_research_search_github: pesquisar repositórios do GitHub.

Ideal para: Fluxos de trabalho de revisão de literatura, consulta de artigos e descoberta de repositórios onde o agente precisa de uma superfície de pesquisa focada em vez de raspagem web geral.

13. Ferramentas de Monitoramento (firecrawl_monitor_*)

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

Ideal 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 de criação recomendado:

Use page ou pages mais goal. O servidor MCP constrói a solicitação do monitor com um agendamento de 30 minutos e a API habilita o julgamento automático de mudanças significativas.

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

Escreva objetivos como instruções de monitor concisas de 2 a 3 frases. Diga o que deve acionar um alerta, preserve qualquer escopo que o usuário tenha dado e inclua exclusões específicas da intenção apenas quando óbvias na solicitação. Ruídos genéricos como espaços em branco, mudanças apenas de formatação, IDs de solicitação, parâmetros de rastreamento, metadados genéricos e cromo de página não relacionado já são tratados pelo juiz, então não os repita em cada objetivo. Se o usuário for vago, mantenha o objetivo amplo; se ele pedir monitoramento amplo ou "qualquer mudança", preserve isso. Se o usuário disser que não se importa com algo, inclua isso explicitamente.

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

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

Passe body quando precisar de alvos de rastreamento, rastreamento de mudanças JSON, retenção personalizada ou controle explícito de judgeEnabled.

{
  "name": "firecrawl_monitor_create",
  "arguments": {
    "body": {
      "name": "Docs monitor",
      "schedule": { "text": "hourly", "timezone": "UTC" },
      "goal": "Alert when docs pages add, remove, or materially change API behavior.",
      "targets": [{ "type": "crawl", "url": "https://example.com/docs" }]
    }
  }
}

Outras ferramentas de monitoramento:

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

Sistema de Logging

O servidor inclui logging abrangente:

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

Exemplo de mensagens de log:

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

Tratamento de Erros

O servidor fornece tratamento robusto de erros:

• Erros de limite de taxa da API 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 funcionalidade
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 por integrarem nosso servidor.

Licença

Licença MIT - veja o arquivo LICENSE para detalhes