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 e scraping em lote
- 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
https://mcp.firecrawl.dev/{FIRECRAWL_API_KEY}/v2/mcp
env FIRECRAWL_API_KEY=fc-YOUR_API_KEY npx -y firecrawl-mcp
npm install -g firecrawl-mcp
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.
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"
}
}
}
}
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
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/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
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:
# 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
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"
}
}
}
}
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
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
}
}
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"
}
}
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
}
}
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
}
}
}
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.
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
}
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.
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...
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
}
# Instalar dependências
npm install
# Compilar
npm run build
# Executar testes
npm test
- 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 MIT — consulte o arquivo LICENSE para mais detalhes