Uma implementação de servidor do Model Context Protocol (MCP) que integra o Firecrawl para recursos de web scraping. Nosso servidor MCP é de código aberto e está disponível no GitHub.
- Web scraping, rastreamento e descoberta
- Busca e extração de conteúdo
- Pesquisa avançada com agente autônomo
- Gerenciamento de sessão de navegador
- Suporte em nuvem e auto-hospedado
- Suporte a HTTP com streaming
Você pode usar nossa URL hospedada ou executar o servidor localmente. Obtenha sua chave de API em https://firecrawl.dev/app/api-keys
URL hospedada remotamente
Instalação manual
Configurando o Cursor 🖥️
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
- Abra as Configurações do Cursor
- Vá em Features > MCP Servers
- Clique em ”+ Add new global MCP server”
- Insira o seguinte código:
Para configurar o Firecrawl MCP no Cursor v0.45.6
- Abra as Configurações do Cursor
- Vá em Features > MCP Servers
- Clique em ”+ Add New MCP Server”
- 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 web scraping. Acesse o Composer com Command+L (Mac), selecione “Agent” ao lado do botão de envio e insira sua consulta.
Adicione isto ao arquivo ./codeium/windsurf/model_config.json:
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 ou https://mcp.firecrawl.dev/{FIRECRAWL_API_KEY}/v2/mcp
Instalação via Smithery (legado)
Para instalar o Firecrawl no Claude Desktop automaticamente usando o Smithery:
Para instalar com um clique, use 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).
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:
Executando no Claude Code
Adicione o servidor MCP do Firecrawl usando a CLI do Claude Code:
Executando no Google Antigravity
O Google Antigravity permite configurar servidores MCP diretamente pela interface do Agent.
- Abra a barra lateral do Agent no Editor ou na visualização Agent Manager
- Clique no menu ”…” (More Actions) e selecione MCP Servers
- Selecione View raw config para abrir o arquivo local
mcp_config.json
- Adicione a seguinte configuração:
- 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.
Para conectar o servidor MCP do Firecrawl no n8n:
- Obtenha sua chave de API da Firecrawl em https://firecrawl.dev/app/api-keys
- No seu fluxo de trabalho do n8n, adicione um nó AI Agent
- Na configuração do nó AI Agent, adicione uma nova Tool
- Selecione MCP Client Tool como o tipo de ferramenta
- Insira o endpoint do servidor MCP (substitua
{YOUR_FIRECRAWL_API_KEY} pela sua chave de API real):
- Defina Server Transport como HTTP Streamable
- Defina Authentication como None
- 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.
Necessário para a API em nuvem
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 autogerenciada com
FIRECRAWL_API_URL
FIRECRAWL_API_URL (opcional): Endpoint de API personalizado para instâncias autogerenciadas
- Exemplo:
https://firecrawl.seu-dominio.com
- Se não for fornecido, a API em nuvem será usada (requer chave de API)
Configuração de tentativas
FIRECRAWL_RETRY_MAX_ATTEMPTS: Número máximo de tentativas (padrão: 3)
FIRECRAWL_RETRY_INITIAL_DELAY: Atraso inicial, em milissegundos, antes da primeira nova tentativa (padrão: 1000)
FIRECRAWL_RETRY_MAX_DELAY: Atraso máximo, em milissegundos, entre novas tentativas (padrão: 10000)
FIRECRAWL_RETRY_BACKOFF_FACTOR: Multiplicador de backoff exponencial (padrão: 2)
Monitoramento do uso de créditos
FIRECRAWL_CREDIT_WARNING_THRESHOLD: Limite de aviso para uso de créditos (padrão: 1000)
FIRECRAWL_CREDIT_CRITICAL_THRESHOLD: Limite crítico para uso de créditos (padrão: 100)
Para uso da API em nuvem com tentativas personalizadas e monitoramento de créditos:
Para instâncias auto-hospedadas:
Adicione o seguinte ao seu claude_desktop_config.json:
O servidor inclui vários parâmetros configuráveis que podem ser definidos por meio de variáveis de ambiente. A seguir estão os valores padrão caso não sejam configurados:
Essas configurações controlam:
-
Comportamento de tentativas (retries)
- Tenta novamente automaticamente as requisições que falharam devido a limites de taxa
- Usa backoff exponencial para evitar sobrecarregar a API
- Exemplo: com as configurações padrão, as novas tentativas serão feitas em:
- 1ª tentativa: atraso de 1 segundo
- 2ª tentativa: atraso de 2 segundos
- 3ª tentativa: atraso de 4 segundos (limitado por maxDelay)
-
Monitoramento do uso de créditos
- Acompanha o consumo de créditos da API para uso em nuvem
- Fornece avisos em limites definidos
- Ajuda a evitar interrupções inesperadas do serviço
- Exemplo: com as configurações padrão:
- Aviso com 1000 créditos restantes
- Alerta crítico com 100 créditos restantes
Limitação de Taxa e Processamento em Lote
O servidor utiliza os recursos integrados de limitação de taxa e processamento em lote do Firecrawl:
- Tratamento automático de limitação de taxa com backoff exponencial
- Processamento paralelo eficiente para operações em lote
- Enfileiramento e controle inteligente de requisições
- Novas tentativas automáticas em caso de erros transitórios
Extraia conteúdo de uma única URL com opções avançadas.
Mapeie um site para descobrir todas as URLs indexadas do site.
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.
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)
Inicia um rastreamento assíncrono com opções avançadas.
5. Verificar status do crawl (firecrawl_check_crawl_status)
Verifique o status de uma tarefa de crawl.
Retorna: Status e progresso da tarefa de rastreamento, incluindo os resultados, se disponíveis.
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:
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.
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:
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.
8. Verificar status do agente (firecrawl_agent_status)
Verifique o status de uma tarefa 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.
9. Criar sessão do navegador (firecrawl_browser_create)
Crie uma sessão de navegador persistente para execução de código por meio do CDP (Chrome DevTools Protocol).
Opções de criação do Browser:
ttl: Tempo de vida total da sessão em segundos (30-3600, opcional)
activityTtl: Tempo limite de inatividade em segundos (10-3600, opcional)
Melhor para: Executar código (Python/JS) que interage com uma página de navegador em tempo real, automação de navegador em várias etapas, sessões com perfis que persistem entre múltiplas chamadas de ferramenta.
Retorna: ID da sessão, URL do CDP e URL de visualização em tempo real.
10. Executar código no navegador (firecrawl_browser_execute)
Executa código em uma sessão de navegador ativa. Oferece suporte a comandos do agent-browser (bash), Python ou JavaScript.
Exemplo em Python usando Playwright:
Opções de execução do navegador:
sessionId: O ID da sessão do navegador (obrigatório)
code: O código a ser executado (obrigatório)
language: bash, python ou node (opcional, padrão é bash)
Comandos comuns do agent-browser (bash):
agent-browser open <url> — Navegar para a URL
agent-browser snapshot — Obter árvore de acessibilidade com referências clicáveis
agent-browser click @e5 — Clicar em elemento pela referência do snapshot
agent-browser type @e3 "text" — Digitar no elemento
agent-browser screenshot [path] — Capturar screenshot
agent-browser scroll down — Rolar a página
agent-browser wait 2000 — Aguardar 2 segundos
Retorno: Resultado da execução, incluindo stdout, stderr e código de saída.
11. Excluir sessão do navegador (firecrawl_browser_delete)
Encerra uma sessão do navegador.
Opções de exclusão do navegador:
sessionId: O ID da sessão do navegador a ser encerrada (obrigatório)
Retorna: Confirmação de sucesso.
12. Listar sessões do navegador (firecrawl_browser_list)
Lista sessões do navegador, que podem ser filtradas por status.
Opções da lista de navegadores:
status: Filtrar por status da sessão — active ou destroyed (opcional)
Retorna: Array de sessões de navegador.
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:
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:
- Faça um fork do repositório
- Crie uma branch para sua feature
- Execute os testes:
npm test
- 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 MIT — consulte o arquivo LICENSE para mais detalhes