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, crawling e descoberta
Busca e extração de conteúdo
Pesquisa aprofundada e scraping em lote
Suporte em nuvem e auto-hospedado
Suporte a SSE

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 de forma remota

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

Executando com npx

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

Instalação manual

npm install -g firecrawl-mcp

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

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 SSE

Para executar o servidor localmente usando Server-Sent Events (SSE) em vez do transporte padrão via stdio:

env SSE_LOCAL=true FIRECRAWL_API_KEY=fc-SUA_CHAVE_DE_API npx -y firecrawl-mcp

Use a URL: http://localhost:3000/v2/sse ou https://mcp.firecrawl.dev/{FIRECRAWL_API_KEY}/v2/sse

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, use um dos botões abaixo…

Para instalação manual, adicione o bloco JSON abaixo ao 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 ambiente de trabalho. 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}"
      }
    }
  }
}

Executando no Claude Desktop

Adicione isto ao arquivo de configuração do Claude:

{
  "mcpServers": {
    "firecrawl": {
      "url": "https://mcp.firecrawl.dev/{YOUR_API_KEY}/v2/sse"
    }
  }
}

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

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 Busca (`firecrawl_search`)

Pesquise na web e, se quiser, extraia conteúdo dos resultados da busca.

{
  "name": "firecrawl_search",
  "arguments": {
    "query": "sua busca",
    "limit": 5,
    "lang": "pt",
    "country": "br",
    "scrapeOptions": {
      "formats": ["markdown"],
      "onlyMainContent": true
    }
  }
}

5. Ferramenta de Rastreamento (`firecrawl_crawl`)

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

{
  "name": "firecrawl_crawl",
  "arguments": {
    "url": "https://exemplo.com",
    "maxDepth": 2,
    "limit": 100,
    "allowExternalLinks": false,
    "deduplicateSimilarURLs": true
  }
}

6. 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 as 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.

7. Ferramenta de Pesquisa Avançada (firecrawl_deep_research)

Realize pesquisas avançadas na web a partir de uma consulta usando rastreamento inteligente, busca e análise com LLM.

{
  "name": "firecrawl_deep_research",
  "arguments": {
    "query": "como a tecnologia de captura de carbono funciona?"
    "maxDepth": 3,
    "timeLimit": 120,
    "maxUrls": 50
  }
}

Argumentos:

query (string, obrigatório): A pergunta de pesquisa ou tópico a ser explorado.
maxDepth (number, opcional): Profundidade recursiva máxima para rastreamento/pesquisa (padrão: 3).
timeLimit (number, opcional): Limite de tempo, em segundos, para a sessão de pesquisa (padrão: 120).
maxUrls (number, opcional): Número máximo de URLs a serem analisadas (padrão: 50).

Retornos:

Análise final gerada por um LLM com base na pesquisa. (data.finalAnalysis)
Pode também incluir ações estruturadas e fontes usadas no processo de pesquisa.

8. Gerar ferramenta LLMs.txt (firecrawl_generate_llmstxt)

Gere um arquivo llms.txt padronizado (e, opcionalmente, llms-full.txt) para um determinado domínio. Esse arquivo define como grandes modelos de linguagem devem interagir com o site.

{
  "name": "firecrawl_generate_llmstxt",
  "arguments": {
    "url": "https://exemplo.com",
    "maxUrls": 20,
    "showFullText": true
  }
}

Argumentos:

url (string, obrigatório): A URL base do site a ser analisado.
maxUrls (number, opcional): Número máximo de URLs a incluir (padrão: 10).
showFullText (boolean, opcional): Indica se o conteúdo de llms-full.txt deve ser incluído na resposta.

Retorna:

Conteúdo gerado do arquivo llms.txt e, opcionalmente, do llms-full.txt (data.llmstxt e/ou data.llmsfulltxt)

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

Casos de uso

Contribuição

​Recursos

​Instalação

​URL hospedada de forma remota

​Executando com npx

​Instalação manual

​Executando no Cursor

​Instalação manual

​Executando no Windsurf

​Executando no modo SSE

​Instalação via Smithery (legado)

​Executando no VS Code

​Executando no Claude Desktop

​Executando no Claude Code

​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 Busca (firecrawl_search)

​5. Ferramenta de Rastreamento (firecrawl_crawl)

​6. Ferramenta de extração (firecrawl_extract)

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

​7. Ferramenta de Pesquisa Avançada (firecrawl_deep_research)

​8. Gerar ferramenta LLMs.txt (firecrawl_generate_llmstxt)

​Sistema de Log

​Tratamento de erros

​Desenvolvimento

​Contribuindo

​Agradecimentos aos colaboradores

​Licença

Recursos

Instalação

URL hospedada de forma remota

Executando com npx

Instalação manual

Executando no Cursor

Instalação manual

Executando no Windsurf

Executando no modo SSE

Instalação via Smithery (legado)

Executando no VS Code

Executando no Claude Desktop

Executando no Claude Code

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 Busca (`firecrawl_search`)

5. Ferramenta de Rastreamento (`firecrawl_crawl`)

6. Ferramenta de extração (`firecrawl_extract`)

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

7. Ferramenta de Pesquisa Avançada (firecrawl_deep_research)

8. Gerar ferramenta LLMs.txt (firecrawl_generate_llmstxt)

Sistema de Log

Tratamento de erros

Desenvolvimento

Contribuindo

Agradecimentos aos colaboradores

Licença