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 o transporte HTTP com streaming em vez do transporte stdio padrão:

env HTTP_STREAMABLE_SERVER=true FIRECRAWL_API_KEY=fc-YOUR_API_KEY 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 no Claude Desktop automaticamente usando o 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 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).

{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "apiKey",
        "description": "Chave de API do Firecrawl",
        "password": true
      }
    ],
    "servers": {
      "firecrawl": {
        "command": "npx",
        "args": ["-y", "firecrawl-mcp"],
        "env": {
          "FIRECRAWL_API_KEY": "${input:apiKey}"
        }
      }
    }
  }
}

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:

{
  "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 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:

{
  "mcpServers": {
    "firecrawl": {
      "url": "https://mcp.firecrawl.dev/v2/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Executando no Claude Code

Adicione o servidor MCP do Firecrawl usando a CLI do Claude Code:

claude mcp add firecrawl -e FIRECRAWL_API_KEY=your-api-key -- npx -y firecrawl-mcp

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:

{
  "mcpServers": {
    "firecrawl": {
      "command": "npx",
      "args": ["-y", "firecrawl-mcp"],
      "env": {
        "FIRECRAWL_API_KEY": "YOUR_FIRECRAWL_API_KEY"
      }
    }
  }
}

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:

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

  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 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:

env HTTP_STREAMABLE_SERVER=true \
    FIRECRAWL_API_KEY=fc-YOUR_API_KEY \
    FIRECRAWL_API_URL=YOUR_FIRECRAWL_INSTANCE \
    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, já que o n8n precisa de 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 o seguinte ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-server-firecrawl": {
      "command": "npx",
      "args": ["-y", "firecrawl-mcp"],
      "env": {
        "FIRECRAWL_API_KEY": "YOUR_API_KEY_HERE",

        "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 meio de variáveis de ambiente. A seguir estão os valores padrão caso não sejam configurados:

const CONFIG = {
  retry: {
    maxAttempts: 3, // Number of retry attempts for rate-limited requests
    initialDelay: 1000, // Initial delay before first retry (in milliseconds)
    maxDelay: 10000, // Maximum delay between retries (in milliseconds)
    backoffFactor: 2, // Multiplier for exponential backoff
  },
  credit: {
    warningThreshold: 1000, // Warn when credit usage reaches this level
    criticalThreshold: 100, // Alerta crítico quando o uso de créditos atingir este nível
  },
};

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

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 Scraping em Lote (`firecrawl_batch_scrape`)

Faça scraping de várias URLs com eficiência, com limitação de taxa integrada 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 verificação do status:

{
  "content": [
    {
      "type": "text",
      "text": "Operação em lote enfileirada 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 do 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 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.

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

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

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

7. Verificar status do crawl (`firecrawl_check_crawl_status`)

Verifique o status de uma tarefa de crawl.

{
  "name": "firecrawl_check_crawl_status",
  "arguments": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Retorna: Status e progresso da tarefa 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 tanto com IA em nuvem quanto com LLMs auto-hospedados.

{
  "name": "firecrawl_extract",
  "arguments": {
    "urls": ["https://example.com/page1", "https://example.com/page2"],
    "prompt": "Extract product information including name, price, and description",
    "systemPrompt": "You are a helpful assistant that extracts product information",
    "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": "Example Product",
        "price": 99.99,
        "description": "This is an example product description"
      }
    }
  ],
  "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 de sistema para guiar o 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.

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 rate limit com backoff
Mensagens de erro detalhadas
Alertas de uso de créditos
Resiliência de rede

Exemplo de resposta de erro:

{
  "content": [
    {
      "type": "text",
      "text": "Error: Rate limit exceeded. Retrying in 2 seconds..."
    }
  ],
  "isError": true
}

Desenvolvimento

# Instalar dependências
npm install

# Build
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
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

Introdução

Novidades

Funcionalidades principais

Webhooks

Guias para desenvolvedores

Casos de uso

Como contribuir

​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 Google Antigravity

​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 Scraping 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 status do crawl (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 Google Antigravity

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 Scraping 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 status do crawl (`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