Pular para o conteúdo principal
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.

Recursos

  • Web scraping, rastreamento e descoberta
  • Busca e extração de conteúdo
  • Pesquisa avançada e scraping em lote
  • Suporte em nuvem e auto-hospedado
  • Suporte a HTTP com streaming

Instalação

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

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

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

Adicionar o servidor MCP do Firecrawl ao Cursor

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
  1. Abra as Configurações do Cursor
  2. Vá em 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á em Features > MCP Servers
  3. Clique em ”+ 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 web scraping. 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:
{
  "mcpServers": {
    "mcp-server-firecrawl": {
      "command": "npx",
      "args": ["-y", "firecrawl-mcp"],
      "env": {
        "FIRECRAWL_API_KEY": "SUA_API_KEY"
      }
    }
  }
}

Executando no modo HTTP com streaming

Para executar o servidor localmente usando transporte HTTP com streaming em vez do transporte padrão stdio:
env HTTP_STREAMABLE_SERVER=true FIRECRAWL_API_KEY=fc-SUA_CHAVE_DA_API npx -y firecrawl-mcp
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 para o Claude Desktop automaticamente via Smithery:
npx -y @smithery/cli install @mendableai/mcp-server-firecrawl --client claude

Executando no VS Code

Para instalar com um clique, selecione um dos botões abaixo… Instalar com NPX no VS Code Instalar com NPX no VS Code Insiders Para instalar manualmente, adicione o bloco JSON abaixo ao seu arquivo User Settings (JSON) no VS Code. Você pode fazer isso pressionando Ctrl + Shift + P e digitando Preferences: Open User Settings (JSON).
{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "apiKey",
        "description": "Chave da API do Firecrawl",
        "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á compartilhar a configuração com outras pessoas:
{
  "inputs": [
    {
      "type": "promptString",
      "id": "apiKey",
      "description": "Chave da API do Firecrawl",
      "password": true
    }
  ],
  "servers": {
    "firecrawl": {
      "command": "npx",
      "args": ["-y", "firecrawl-mcp"],
      "env": {
        "FIRECRAWL_API_KEY": "${input:apiKey}"
      }
    }
  }
}
Nota: Alguns usuários relataram problemas ao adicionar o servidor MCP ao VS Code devido à forma como ele valida JSON com um formato de esquema desatualizado (microsoft/vscode#155379). Isso afeta várias ferramentas MCP, incluindo o Firecrawl. Solução alternativa: Desative a validação de JSON no VS Code para que o servidor MCP carregue corretamente.
Veja a referência: directus/directus#25906 (comment).
O servidor MCP ainda funciona normalmente quando acionado 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 do esquema.

Executando no Claude Desktop

Adicione isto ao arquivo de configuração do Claude:
{
  "mcpServers": {
    "firecrawl": {
      "url": "https://mcp.firecrawl.dev/v2/mcp",
      "headers": {
        "Authorization": "Bearer SUA_CHAVE_DE_API"
      }
    }
  }
}

Executando no Claude Code

Adicione o servidor MCP do Firecrawl usando a CLI do Claude Code:
claude mcp add firecrawl -e FIRECRAWL_API_KEY=sua-chave-de-API -- npx -y firecrawl-mcp

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 do n8n, adicione um nó AI Agent
  3. Na configuração do AI Agent, adicione uma nova Tool
  4. Selecione MCP Client Tool como tipo de ferramenta
  5. Insira o endpoint do servidor MCP (substitua {YOUR_FIRECRAWL_API_KEY} pela sua chave de API):
  https://mcp.firecrawl.dev/{SUA_CHAVE_API_FIRECRAWL}/v2/mcp
  1. Defina Server Transport como HTTP Streamable
  2. Defina Authentication como None
  3. Em Tools to include, você pode selecionar All, Selected ou All Except — isso disponibilizará as ferramentas do Firecrawl (scrape, crawl, map, search, extract etc.)
Para implantações self-hosted, execute o servidor MCP com npx e ative o modo de transporte HTTP:
env HTTP_STREAMABLE_SERVER=true \
    FIRECRAWL_API_KEY=fc-SUA_CHAVE_DA_API \
    FIRECRAWL_API_URL=SUA_INSTANCIA_DO_FIRECRAWL \
    npx -y firecrawl-mcp
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, pois o n8n requer transporte HTTP.

Configuração

Variáveis de Ambiente

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ções opcionais

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)

Exemplos de configuração

Para uso da API em nuvem com tentativas personalizadas e monitoramento de créditos:
# Necessário para a API em nuvem
export FIRECRAWL_API_KEY=your-api-key

# Configuração opcional de tentativas
export FIRECRAWL_RETRY_MAX_ATTEMPTS=5        # Aumentar o número máximo de tentativas
export FIRECRAWL_RETRY_INITIAL_DELAY=2000    # Começar com atraso de 2s
export FIRECRAWL_RETRY_MAX_DELAY=30000       # Atraso máximo de 30s
export FIRECRAWL_RETRY_BACKOFF_FACTOR=3      # Backoff mais agressivo

# Monitoramento opcional de créditos
export FIRECRAWL_CREDIT_WARNING_THRESHOLD=2000    # Aviso a partir de 2000 créditos
export FIRECRAWL_CREDIT_CRITICAL_THRESHOLD=500    # Crítico a partir de 500 créditos
Para instâncias auto-hospedadas:
# Necessário para auto-hospedado
export FIRECRAWL_API_URL=https://firecrawl.seu-dominio.com

# Autenticação opcional para auto-hospedado
export FIRECRAWL_API_KEY=sua-api-key  # Se sua instância exigir autenticação

# Configuração personalizada de novas tentativas
export FIRECRAWL_RETRY_MAX_ATTEMPTS=10
export FIRECRAWL_RETRY_INITIAL_DELAY=500     # Comece com novas tentativas mais rápidas

Configuração personalizada com o Claude Desktop

Adicione isto ao seu claude_desktop_config.json:
{
  "mcpServers": {
    "mcp-server-firecrawl": {
      "command": "npx",
      "args": ["-y", "firecrawl-mcp"],
      "env": {
        "FIRECRAWL_API_KEY": "SUA_CHAVE_DE API_AQUI",

        "FIRECRAWL_RETRY_MAX_ATTEMPTS": "5",
        "FIRECRAWL_RETRY_INITIAL_DELAY": "2000",
        "FIRECRAWL_RETRY_MAX_DELAY": "30000",
        "FIRECRAWL_RETRY_BACKOFF_FACTOR": "3",

        "FIRECRAWL_CREDIT_WARNING_THRESHOLD": "2000",
        "FIRECRAWL_CREDIT_CRITICAL_THRESHOLD": "500"
      }
    }
  }
}

Configuração do sistema

O servidor inclui vários parâmetros configuráveis que podem ser definidos por variáveis de ambiente. A seguir estão os valores padrão, caso não sejam configurados:
const CONFIG = {
  retry: {
    maxAttempts: 3, // Número de tentativas para solicitações limitadas por taxa
    initialDelay: 1000, // Atraso inicial antes da primeira nova tentativa (em milissegundos)
    maxDelay: 10000, // Atraso máximo entre novas tentativas (em milissegundos)
    backoffFactor: 2, // Multiplicador para backoff exponencial
  },
  credit: {
    warningThreshold: 1000, // Avisar quando o uso de crédito atingir este nível
    criticalThreshold: 100, // Alerta crítico quando o uso de crédito atingir este nível
  },
};
Essas configurações controlam:
  1. Comportamento de novas tentativas
    • Retenta automaticamente solicitaçõ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 ocorrerão em:
      • 1ª nova tentativa: atraso de 1 segundo
      • 2ª nova tentativa: atraso de 2 segundos
      • 3ª nova tentativa: atraso de 4 segundos (limitado por maxDelay)
  2. Monitoramento do uso de créditos
    • Acompanha o consumo de créditos da API para uso na nuvem
    • Fornece avisos em limites definidos
    • Ajuda a evitar interrupções inesperadas do serviço
    • Exemplo: Com as configurações padrão:
      • Aviso ao restarem 1000 créditos
      • Alerta crítico ao restarem 100 créditos

Limitação de taxa e processamento em lote

O servidor utiliza os recursos nativos do Firecrawl para limitação de taxa e processamento em lote:
  • Tratamento automático de limites de taxa com backoff exponencial
  • Processamento paralelo eficiente para operações em lote
  • Enfileiramento e controle inteligente de solicitações
  • Tentativas automáticas para erros transitórios

Ferramentas disponíveis

1. Ferramenta de scraping (firecrawl_scrape)

Extraia conteúdo de uma única URL com opções avançadas.
{
  "name": "firecrawl_scrape",
  "arguments": {
    "url": "https://example.com",
    "formatos": ["markdown"],
    "onlyMainContent": true,
    "waitFor": 1000,
    "timeout": 30000,
    "mobile": false,
    "includeTags": ["article", "main"],
    "excludeTags": ["nav", "footer"],
    "skipTlsVerification": false
  }
}

2. Ferramenta de Scrape em Lote (firecrawl_batch_scrape)

Extraia dados de várias URLs com eficiência, com controle de taxa integrado e processamento paralelo.
{
  "name": "firecrawl_batch_scrape",
  "arguments": {
    "urls": ["https://example1.com", "https://example2.com"],
    "options": {
      "formats": ["markdown"],
      "onlyMainContent": true
    }
  }
}
A resposta inclui o ID da operação para verificar o status:
{
  "content": [
    {
      "type": "text",
      "text": "Operação em lote colocada na fila com ID: batch_1. Use firecrawl_check_batch_status para verificar o andamento."
    }
  ],
  "isError": false
}

3. Verificar o status do lote (firecrawl_check_batch_status)

Verifique o status de uma operação em lote.
{
  "name": "firecrawl_check_batch_status",
  "arguments": {
    "id": "batch_1"
  }
}

4. Ferramenta de Mapeamento (firecrawl_map)

Mapeie um site para descobrir todas as URLs indexadas no site.
{
  "name": "firecrawl_map",
  "arguments": {
    "url": "https://example.com",
    "search": "blog",
    "sitemap": "include",
    "includeSubdomains": false,
    "limit": 100,
    "ignoreQueryParameters": true
  }
}

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 devem ser incluídos subdomínios no mapeamento
  • limit: Número máximo de URLs a retornar
  • ignoreQueryParameters: Se os parâmetros de query devem ser ignorados ao mapear
Ideal para: Descobrir URLs em um site antes de decidir o que extrair; encontrar seções específicas de um site. Retorna: Uma lista (array) de URLs encontradas no site. Pesquise na web e, opcionalmente, extraia conteúdo dos resultados da busca.
{
  "name": "firecrawl_search",
  "arguments": {
    "query": "sua consulta de busca",
    "limit": 5,
    "lang": "en",
    "country": "us",
    "scrapeOptions": {
      "formatos": ["markdown"],
      "onlyMainContent": true
    }
  }
}

6. Ferramenta de Rastreamento (firecrawl_crawl)

Inicie uma varredura assíncrona com opções avançadas.
{
  "name": "firecrawl_crawl",
  "arguments": {
    "url": "https://example.com",
    "maxDepth": 2,
    "limit": 100,
    "allowExternalLinks": false,
    "deduplicateSimilarURLs": true
  }
}

7. Verificar o status do rastreamento (firecrawl_check_crawl_status)

Verifique o status de uma tarefa de rastreamento.
{
  "name": "firecrawl_check_crawl_status",
  "arguments": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
Retorna: Status e progresso do job de rastreamento, incluindo os resultados, se disponíveis.

8. Ferramenta de Extração (firecrawl_extract)

Extraia informações estruturadas de páginas da web usando LLMs. Suporta extração com IA em nuvem e LLMs auto-hospedados.
{
  "name": "firecrawl_extract",
  "arguments": {
    "urls": ["https://example.com/page1", "https://example.com/page2"],
    "prompt": "Extraia informações do produto incluindo nome, preço e descrição",
    "systemPrompt": "Você é um assistente útil que extrai informações de produtos",
    "schema": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "price": { "type": "number" },
        "description": { "type": "string" }
      },
      "required": ["name", "price"]
    },
    "allowExternalLinks": false,
    "enableWebSearch": false,
    "includeSubdomains": false
  }
}
Exemplo de resposta:
{
  "content": [
    {
      "type": "text",
      "text": {
        "name": "Produto de Exemplo",
        "price": 99.99,
        "description": "Esta é uma descrição de produto de exemplo"
      }
    }
  ],
  "isError": false
}

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
  • systemPrompt: Prompt do sistema para orientar o LLM
  • schema: Esquema JSON para extração de dados estruturados
  • allowExternalLinks: Permite extração de links externos
  • enableWebSearch: Habilita pesquisa na web para contexto adicional
  • includeSubdomains: Inclui subdomínios na extração
Ao usar uma instância self-hosted, a extração utilizará o LLM que você configurou. Na API em nuvem, ela usa o serviço de LLM gerenciado do Firecrawl.

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:
[INFO] Firecrawl MCP Server inicializado com sucesso
[INFO] Iniciando a raspagem da URL: https://example.com
[INFO] Operação em lote adicionada à fila com ID: batch_1
[WARNING] O uso de créditos atingiu o limite de aviso
[ERROR] Limite de requisições excedido, tentando novamente em 2s...

Tratamento de erros

O servidor oferece um tratamento de erros robusto:
  • Novas tentativas automáticas para erros transitórios
  • Tratamento de limites de taxa com backoff
  • Mensagens de erro detalhadas
  • Alertas sobre uso de créditos
  • Resiliência de rede
Exemplo de resposta de erro:
{
  "content": [
    {
      "type": "text",
      "text": "Erro: limite de taxa excedido. Nova tentativa em 2 segundos..."
    }
  ],
  "isError": true
}

Desenvolvimento

# Instalar dependências
npm install

# Compilar
npm run build

# Executar testes
npm test

Contribuindo

  1. Faça um fork do repositório
  2. Crie uma branch para sua feature
  3. Execute os testes: npm test
  4. Abra 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