Servidor MCP do Firecrawl

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

Abra as Configurações do Cursor
Vá em Features > MCP Servers
Clique em ”+ Add new global MCP server”

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

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.

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…

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:

Obtenha sua chave de API do Firecrawl em https://firecrawl.dev/app/api-keys
No seu fluxo do n8n, adicione um nó AI Agent
Na configuração do AI Agent, adicione uma nova Tool
Selecione MCP Client Tool como tipo de ferramenta
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

Defina Server Transport como HTTP Streamable
Defina Authentication como None
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:

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)
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.

5. Search Tool (`firecrawl_search`)

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

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

Comece

Recursos Padrão

Recursos agênticos

Webhooks

Guias do Desenvolvedor

Casos de uso

Contribuindo

​Recursos

​Instalação

​URL hospedada remotamente

​Executando com npx

​Instalação Manual

​Executando no Cursor

​Instalação manual

​Executando no Windsurf

​Executando no modo HTTP com streaming

​Instalação via Smithery (legado)

​Executando no VS Code

​Executando no Claude Desktop

​Executando no Claude Code

​Executando no n8n

​Configuração

​Variáveis de Ambiente

​Necessário para a API em nuvem

​Configurações opcionais

Configuração de tentativas

Monitoramento do uso de créditos

​Exemplos de configuração

​Configuração personalizada com o Claude Desktop

​Configuração do sistema

​Limitação de taxa e processamento em lote

​Ferramentas disponíveis

​1. Ferramenta de scraping (firecrawl_scrape)

​2. Ferramenta de Scrape em Lote (firecrawl_batch_scrape)

​3. Verificar o status do lote (firecrawl_check_batch_status)

​4. Ferramenta de Mapeamento (firecrawl_map)

​Opções da ferramenta Map:

​5. Search Tool (firecrawl_search)

​6. Ferramenta de Rastreamento (firecrawl_crawl)

​7. Verificar o status do rastreamento (firecrawl_check_crawl_status)

​8. Ferramenta de Extração (firecrawl_extract)

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

​Sistema de Log

​Tratamento de erros

​Desenvolvimento

​Contribuindo

​Agradecimentos aos colaboradores

​Licença

Recursos

Instalação

URL hospedada remotamente

Executando com npx

Instalação Manual

Executando no Cursor

Instalação manual

Executando no Windsurf

Executando no modo HTTP com streaming

Instalação via Smithery (legado)

Executando no VS Code

Executando no Claude Desktop

Executando no Claude Code

Executando no n8n

Configuração

Variáveis de Ambiente

Necessário para a API em nuvem

Configurações opcionais

Exemplos de configuração

Configuração personalizada com o Claude Desktop

Configuração do sistema

Limitação de taxa e processamento em lote

Ferramentas disponíveis

1. Ferramenta de scraping (`firecrawl_scrape`)

2. Ferramenta de Scrape em Lote (`firecrawl_batch_scrape`)

3. Verificar o status do lote (`firecrawl_check_batch_status`)

4. Ferramenta de Mapeamento (`firecrawl_map`)

Opções da ferramenta Map:

5. Search Tool (`firecrawl_search`)

6. Ferramenta de Rastreamento (`firecrawl_crawl`)

7. Verificar o status do rastreamento (`firecrawl_check_crawl_status`)

8. Ferramenta de Extração (`firecrawl_extract`)

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

Sistema de Log

Tratamento de erros

Desenvolvimento

Contribuindo

Agradecimentos aos colaboradores

Licença