Pular para o conteúdo principal
Uma implementação de servidor do Model Context Protocol (MCP) que integra o Firecrawl para busca, scraping e interagir com a web. Nosso servidor MCP é de código aberto e está disponível no GitHub.

Recursos

  • Fazer uma busca na web e obter o conteúdo completo da página
  • Fazer scraping de qualquer URL para obter dados estruturados limpos
  • Processar arquivos locais, como PDFs, DOCX, XLSX e HTML
  • Interagir com páginas — clicar, navegar e executar ações
  • Pesquisa avançada com agente autônomo
  • Suporte em nuvem e auto-hospedado
  • Suporte a HTTP com streaming

Instalação

Você pode usar nossa URL hospedada remotamente ou executar o servidor localmente. Obtenha sua chave de API em https://firecrawl.dev/app/api-keys
Sem chave de API? Conecte-se a https://mcp.firecrawl.dev/v2/mcp para usar o plano gratuito remoto sem chave. É gratuito e tem limite de taxa por IP; veja limite de taxa para a lista atual de ferramentas sem chave. Defina FIRECRAWL_API_KEY para desbloquear todas as ferramentas do MCP e limites mais altos.

URL hospedada remotamente

Conecte-se sem uma API key para começar no tier Free remoto sem chave (com limite de requisições por IP; consulte Limites de taxa para a lista atual de ferramentas):
Com uma API key, envie-a no header Authorization para desbloquear todas as ferramentas, além de limites maiores:

Executando com npx

Instalação manual

Executando no Cursor

Instale o servidor hospedado keyless com um clique (não requer API key): Adicionar o servidor MCP do Firecrawl ao Cursor Ou adicione-o manualmente ao ~/.cursor/mcp.json:

Executando localmente com uma chave de API

Observação: requer o Cursor na versão 0.45.6 ou superior. 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 de servidor MCP do Cursor Para configurar o Firecrawl MCP no Cursor v0.48.6
  1. Abra as Configurações do Cursor
  2. Vá em Features > MCP Servers
  3. Clique ”+ Add new global MCP server”
  4. Enter the following code:
Para configurar o Firecrawl MCP no Cursor v0.45.6
  1. Abra as Configurações do Cursor
  2. Vá em Features > MCP Servers
  3. Clique ”+ Add New MCP Server”
  4. Insira o seguinte:
    • Name: “firecrawl-mcp” (ou o nome de sua preferência)
    • Type: “command”
    • Command: env FIRECRAWL_API_KEY=your-api-key npx -y firecrawl-mcp
Se você estiver no Windows e tiver 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, crie uma conta e obtenha-a 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 dados da web. Acesse o Composer com Command+L (Mac), selecione “Agent” ao lado do botão de envio e insira sua consulta.

Executando no Windsurf

Adicione isto ao arquivo ./codeium/windsurf/model_config.json:

Executando no modo HTTP com streaming

Para executar o servidor localmente usando o transporte HTTP com streaming em vez do transporte stdio padrão:
Use a URL: http://localhost:3000/v2/mcp localmente ou a versão hospedada https://mcp.firecrawl.dev/v2/mcp

Instalação via Smithery (legado)

Para instalar o Firecrawl no Claude Desktop automaticamente usando o Smithery:

Executando no VS Code

Para instalar com um clique, use um dos botões de instalação abaixo… Instalar com NPX no VS Code Instalar com NPX no VS Code Insiders 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).
Opcionalmente, você também pode adicioná-lo a um arquivo chamado .vscode/mcp.json no seu espaço de trabalho. Isso permitirá que você compartilhe essa configuração com outras pessoas:
Nota: Alguns usuários relataram problemas ao adicionar o servidor MCP ao VS Code devido à forma como ele valida JSON com um formato de schema desatualizado (microsoft/vscode#155379). Isso afeta várias ferramentas MCP, incluindo Firecrawl. Solução alternativa: Desative a validação de JSON no VS Code para permitir que o servidor MCP seja carregado corretamente. Consulte a referência: directus/directus#25906 (comment). O servidor MCP continua funcionando normalmente quando invocado por outras extensões, mas o problema ocorre especificamente ao registrá-lo diretamente na lista de servidores MCP. Planejamos adicionar orientações assim que o VS Code atualizar a validação de schema.

Executando no Claude Desktop

Adicione o seguinte ao arquivo de configuração do Claude:
Se você receber um erro “Não foi possível se conectar ao servidor MCP”, sua versão do Claude Desktop pode não oferecer suporte a transporte HTTP com streaming. Use a abordagem local com npx em vez disso (requer Node.js):
Se você vir um erro spawn npx ENOENT, o Node.js não está instalado ou não está no PATH do sistema. Instale o Node.js em nodejs.org (versão LTS) e, em seguida, reinicie completamente o Claude Desktop. No Windows, você também pode executar where npx no Prompt de Comando e usar o caminho completo (por exemplo, C:\\Program Files\\nodejs\\npx.cmd) como valor de command.

Executando no Claude Code

Adicione o servidor MCP do Firecrawl usando a CLI do Claude Code. Você pode usar a URL hospedada remotamente ou executar localmente:

Executando no Google Antigravity

O Google Antigravity permite configurar servidores MCP diretamente pela interface do Agent. Instalação do MCP no Antigravity
  1. Abra a barra lateral do Agent no Editor ou na visualização Agent Manager
  2. Clique no menu ”…” (More Actions) e selecione MCP Servers
  3. Selecione View raw config para abrir o arquivo local mcp_config.json
  4. Adicione a seguinte configuração:
  1. Salve o arquivo e clique em Refresh na interface Antigravity MCP para ver as novas ferramentas
Substitua YOUR_FIRECRAWL_API_KEY pela sua chave de API de https://firecrawl.dev/app/api-keys.

Executando no n8n

Para conectar o servidor MCP do Firecrawl no n8n:
  1. Obtenha sua chave de API do Firecrawl em https://firecrawl.dev/app/api-keys
  2. No seu fluxo de trabalho do n8n, adicione um nó AI Agent
  3. Na configuração do nó AI Agent, adicione uma nova Tool
  4. Selecione MCP Client Tool como o tipo de ferramenta
  5. Insira o endpoint do servidor MCP:
  1. Defina Server Transport como HTTP Streamable
  2. Defina Authentication como Bearer e cole sua chave de API do Firecrawl, ou deixe como None para usar o plano gratuito sem chave
  3. Em Tools to include, você pode selecionar All, Selected ou All Except – isso expõe as ferramentas do Firecrawl (scrape, crawl, map, search, extract, etc.)
Para implantações autohospedadas, execute o servidor MCP com npx e habilite o modo de transporte HTTP:
Isso iniciará o servidor em http://localhost:3000/v2/mcp, que você pode usar no seu workflow do n8n como endpoint. A variável de ambiente HTTP_STREAMABLE_SERVER=true é obrigatória, já que o n8n precisa de transporte HTTP.

Configuração

Variáveis de Ambiente

API em nuvem e auto-hospedada

  • FIRECRAWL_API_KEY: Sua chave de API do Firecrawl
    • Obrigatória ao usar a API em 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.seu-dominio.com
    • Se não for fornecido, a API em nuvem será usada (requer chave de API)

Exemplos de configuração

Para uso da API em nuvem:
Para instâncias auto-hospedadas:

Configuração personalizada com o Claude Desktop

Adicione o seguinte ao seu claude_desktop_config.json:

MCP hospedado vs MCP local

O servidor MCP hospedado é otimizado para uso remoto seguro. Algumas opções disponíveis ao executar o servidor MCP localmente são limitadas ou indisponíveis no uso remoto:
  • O modo keyless hospedado expõe apenas as ferramentas compatíveis com keyless e está sujeito a limite de taxa por IP.
  • A leitura de arquivos locais só está disponível quando você executa o servidor MCP localmente.
  • Webhooks e caminhos de arquivos locais devem ser configurados a partir de um servidor MCP local ou auto-hospedado quando o agente precisar de acesso a recursos locais.

Limites de taxa

Os limites de taxa são aplicados pelo Firecrawl. Use uma chave de API para ter limites mais altos e acesso ao conjunto completo de ferramentas.

Ferramentas disponíveis

1. Ferramenta de scraping (firecrawl_scrape)

Extraia conteúdo de uma única URL com opções avançadas.
Para ocultar informações de identificação pessoal, inclua redactPII nos argumentos da ferramenta de scraping.

2. Ferramenta de Mapeamento (firecrawl_map)

Mapeie um site para descobrir todas as URLs indexadas do site.

Opções da ferramenta Map:

  • url: A URL base do site a ser mapeado
  • search: Termo de pesquisa opcional para filtrar URLs
  • sitemap: Controla o uso do sitemap — “include”, “skip” ou “only”
  • includeSubdomains: Se deve incluir subdomínios no mapeamento
  • limit: Número máximo de URLs a serem retornadas
  • ignoreQueryParameters: Se deve ignorar parâmetros de consulta ao mapear
Ideal para: Descobrir URLs em um site antes de decidir o que extrair; encontrar seções específicas de um site. Retorna: Array de URLs encontradas no site. Pesquise na web e, opcionalmente, extraia conteúdo dos resultados da busca.

Opções da Search Tool:

  • query: A string da consulta de busca (obrigatório)
  • limit: Número máximo de resultados a serem retornados
  • location: Localização geográfica para os resultados de busca
  • tbs: Filtro de busca baseado em tempo (por exemplo, qdr:d para o último dia, qdr:w para a última semana, qdr:m para o último mês)
  • filter: Filtro adicional de busca
  • sources: Array de tipos de fonte a serem pesquisados (web, images, news)
  • scrapeOptions: Opções para scraping das páginas de resultados de busca
  • enterprise: Array de opções de enterprise (default, anon, zdr)

4. Ferramenta Parse (firecrawl_parse)

Converta um arquivo local, como um documento PDF, DOCX, XLSX ou HTML, em dados limpos e prontos para LLM.
Quando você executa o Firecrawl MCP localmente em uma instância da API do Firecrawl com FIRECRAWL_API_URL, o servidor MCP pode ler filePath diretamente e envia os bytes do arquivo para /v2/parse. Quando você usa o servidor MCP remoto hospedado, o servidor hospedado não consegue ler arquivos da sua máquina. Nesse caso, firecrawl_parse usa um fluxo em duas etapas que também funciona na URL remota sem chave:
  1. Chame firecrawl_parse com filePath. A ferramenta retorna um comando de upload pré-preenchido e um nextToolCall contendo um uploadRef.
  2. Execute o comando de upload na máquina que consegue ler o arquivo e, em seguida, chame firecrawl_parse novamente com o uploadRef retornado.
O comando de upload envia os bytes do arquivo para um destino de upload assinado com validade curta. Ele não inclui sua chave de API do Firecrawl.

Opções da ferramenta Parse:

  • filePath: Caminho local para o arquivo que você quer analisar. Use isto na primeira chamada.
  • uploadRef: Referência retornada pela primeira chamada ao hosted-MCP. Use isto na segunda chamada, depois que o upload for concluído com sucesso.
  • formats: Formatos de resultado. O padrão é markdown.
  • parsers: Controles do parser, como opções de análise de PDF.
  • contentType: Substituição opcional do tipo MIME do arquivo.
  • declaredSizeBytes: Indicação opcional do tamanho do arquivo. Os arquivos têm limite de 50 MB.
Ideal para: Documentos locais ou não públicos que não estejam disponíveis em uma URL pública. Não recomendado para: URLs públicas de documentos. Use firecrawl_scrape em vez disso; ele detectará e analisará documentos a partir de URLs.

5. Ferramenta de Rastreamento (firecrawl_crawl)

Inicia um rastreamento assíncrono com opções avançadas.

6. Verificar status do rastreamento (firecrawl_check_crawl_status)

Verifique o status de um job de rastreamento.
Retorna: Status e progresso do job de rastreamento, incluindo os resultados, se disponíveis.

7. Ferramenta de extração (firecrawl_extract)

Extraia informações estruturadas de páginas da web usando LLMs. Suporta extração tanto com IA em nuvem quanto com LLMs auto-hospedados.
Exemplo de resposta:

Opções da ferramenta de extração:

  • urls: Array de URLs das quais extrair informações
  • prompt: Prompt personalizado para a extração pelo LLM
  • schema: Esquema JSON para extração de dados estruturados
  • allowExternalLinks: Permite extração a partir de links externos
  • enableWebSearch: Habilita busca na web para contexto adicional
  • includeSubdomains: Inclui subdomínios na extração
Ao usar uma instância auto-hospedada, a extração usará o LLM que você configurou. Na API em nuvem, ela usa o serviço de LLM gerenciado do Firecrawl.

8. Agent Tool (firecrawl_agent)

Agente autônomo de pesquisa na web que navega independentemente pela internet, busca informações, percorre páginas e extrai dados estruturados com base na sua consulta. Esse agente é executado de forma assíncrona — ele retorna imediatamente um ID de job, e você faz polling em firecrawl_agent_status para verificar quando for concluído e recuperar os resultados.
Você também pode fornecer URLs específicas nas quais o agente deve se concentrar:

Opções da ferramenta de agente:

  • prompt: Descrição em linguagem natural dos dados que você quer (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
Melhor para: Tarefas de pesquisa complexas quando você não sabe as URLs exatas; coleta de dados de múltiplas fontes; encontrar informações espalhadas pela web; extrair dados de SPAs pesadas em JavaScript que falham com a raspagem comum. Retorna: ID do job para verificação de status. Use firecrawl_agent_status para consultar os resultados periodicamente.

9. Verificar status do agente (firecrawl_agent_status)

Verifique o status de um job do agente e recupere os resultados quando ela for concluída. Faça verificações (polling) a cada 15–30 segundos e mantenha por pelo menos 2–3 minutos antes de considerar a solicitação como falha.

Opções de status do agente:

  • id: O ID da tarefa do agente retornado por firecrawl_agent (obrigatório)
Possíveis status:
  • processing: O agente ainda está pesquisando — continue consultando periodicamente
  • completed: Pesquisa concluída — a resposta inclui os dados extraídos
  • failed: Ocorreu um erro
Retorna: Status, progresso e resultados (se concluída) da tarefa do agente.

10. Interagir com uma página (firecrawl_interact)

Interaja com uma página em uma sessão ativa no navegador: clique em botões, preencha formulários, extraia conteúdo dinâmico ou navegue mais a fundo. Use um dos dois modos de direcionamento:
  • Passe url para abrir e interagir com uma nova página em uma única chamada MCP.
  • Passe scrapeId de uma chamada anterior de firecrawl_scrape para reutilizar a página já carregada.
Não passe url e scrapeId ao mesmo tempo. Forneça prompt ou code. scrapeOptions só pode ser usado no modo url. Exemplo de modo URL:
Exemplo de reutilização do scraping:

Opções da ferramenta Interact:

  • url: Página com a qual interagir; abre a sessão para você. Use isto ou scrapeId.
  • scrapeId: O ID do job de scraping de uma chamada anterior a firecrawl_scrape. Use isto ou url.
  • prompt: Instrução em linguagem natural que descreve a ação a ser executada. Forneça prompt ou code.
  • code: Código a ser executado na sessão do navegador. Forneça code ou prompt.
  • language: bash, python ou node (opcional, o padrão é node, usado apenas com code).
  • timeout: Tempo limite de execução em segundos, de 1 a 300 (opcional, o padrão é 30).
  • scrapeOptions: Controles opcionais de scraping usados apenas no modo url.
Ideal para: Fluxos de trabalho com várias etapas em uma única página — pesquisar em um site, clicar nos resultados, preencher formulários e extrair dados que exigem interação. Retorna: Resultado da interação, incluindo o resultado e URLs de visualização em tempo real.

11. Encerrar sessão de interação (firecrawl_interact_stop)

Encerre uma sessão de interação de uma página extraída. Use isso quando terminar de interagir para liberar recursos.

Opções para interromper a interação:

  • scrapeId: O ID do scraping da sessão a ser interrompida (obrigatório)
Retorna: Confirmação de que a sessão foi interrompida.

Sistema de Log

O servidor inclui registros abrangentes:
  • Status e progresso da operação
  • Métricas de desempenho
  • Monitoramento do uso de créditos
  • Acompanhamento de limites de taxa
  • Condições de erro
Exemplos de mensagens de log:

Tratamento de Erros

O servidor oferece um tratamento de erros robusto:
  • Novas tentativas automáticas para erros transitórios
  • Tratamento de rate limit com backoff
  • Mensagens de erro detalhadas
  • Alertas de uso de créditos
  • Resiliência de rede
Exemplo de resposta de erro:

Desenvolvimento

Contribuindo

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

Agradecimentos aos colaboradores

Obrigado a @vrknetha e @cawstudios pela implementação inicial! Obrigado à MCP.so e à Klavis AI pela hospedagem, e a @gstarwd, @xiangkaiz e @zihaolin96 por integrarem nosso servidor.

Licença

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