Servidor MCP de Firecrawl

Una implementación de servidor de Protocolo de contexto de modelo (MCP) que se integra con Firecrawl para capacidades de raspado web.

¡Muchas gracias a @vrknetha y @cawstudios por la implementación inicial!

Características

• Soporte para raspar, rastrear, buscar, extraer, investigar en profundidad y raspar por lotes

• Web scraping con renderizado JS

• Descubrimiento y rastreo de URL

• Búsqueda web con extracción de contenido

• Reintentos automáticos con retroceso exponencial

• • Procesamiento por lotes eficiente con limitación de velocidad incorporada

• Monitoreo del uso de crédito para la API en la nube

• Sistema de registro integral

• Compatibilidad con instancias de FireCrawl alojadas en la nube y autoalojadas

• Compatibilidad con ventanas gráficas móviles y de escritorio

• Filtrado de contenido inteligente con inclusión/exclusión de etiquetas

Related MCP server: OneSearch MCP Server

Instalación

Ejecutando con npx

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

Instalación manual

npm install -g firecrawl-mcp

Ejecutando en el cursor

Configuración del cursor 🖥️ Nota: Requiere la versión 0.45.6+ del cursor

Para configurar FireCrawl MCP en Cursor:

1. Abrir configuración del cursor

2. Vaya a Características > Servidores MCP

3. Haga clic en "+ Agregar nuevo servidor MCP"

4. Introduzca lo siguiente:

   • Nombre: "firecrawl-mcp" (o el nombre que prefiera)

   • Tipo: "comando"

   • Comando: env FIRECRAWL_API_KEY=your-api-key npx -y firecrawl-mcp

Si está usando Windows y tiene problemas, pruebe cmd /c "set FIRECRAWL_API_KEY=your-api-key && npx -y firecrawl-mcp"

Reemplace your-api-key con su clave API de FireCrawl.

Tras añadir, actualice la lista de servidores MCP para ver las nuevas herramientas. El agente de Composer usará automáticamente FireCrawl MCP cuando corresponda, pero puede solicitarlo explícitamente describiendo sus necesidades de web scraping. Acceda a Composer con Comando+L (Mac), seleccione "Agente" junto al botón de envío e introduzca su consulta.

Corriendo en Windsurf

Agregue esto a su ./codeium/windsurf/model_config.json :

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

Instalación mediante herrería (legado)

Para instalar FireCrawl para Claude Desktop automáticamente a través de Smithery :

npx -y @smithery/cli install @mendableai/mcp-server-firecrawl --client claude

Configuración

Variables de entorno

Requerido para la API de la nube

• FIRECRAWL_API_KEY : Su clave API de FireCrawl

  • Obligatorio al utilizar la API en la nube (predeterminado)

  • Opcional cuando se utiliza una instancia autohospedada con FIRECRAWL_API_URL

• FIRECRAWL_API_URL (opcional): punto final de API personalizado para instancias autohospedadas

  • Ejemplo: https://firecrawl.your-domain.com

  • Si no se proporciona, se utilizará la API en la nube (requiere clave API)

Configuración opcional

Reintentar configuración

• FIRECRAWL_RETRY_MAX_ATTEMPTS : Número máximo de intentos de reintento (predeterminado: 3)

• FIRECRAWL_RETRY_INITIAL_DELAY : Retraso inicial en milisegundos antes del primer reintento (valor predeterminado: 1000)

• FIRECRAWL_RETRY_MAX_DELAY : Retraso máximo en milisegundos entre reintentos (valor predeterminado: 10000)

• FIRECRAWL_RETRY_BACKOFF_FACTOR : Multiplicador de retroceso exponencial (predeterminado: 2)

Monitoreo del uso del crédito

• FIRECRAWL_CREDIT_WARNING_THRESHOLD : Umbral de advertencia de uso de crédito (predeterminado: 1000)

• FIRECRAWL_CREDIT_CRITICAL_THRESHOLD : Umbral crítico de uso de crédito (predeterminado: 100)

Ejemplos de configuración

Para el uso de API en la nube con reintentos personalizados y monitoreo de crédito:

# Required for cloud API
export FIRECRAWL_API_KEY=your-api-key

# Optional retry configuration
export FIRECRAWL_RETRY_MAX_ATTEMPTS=5        # Increase max retry attempts
export FIRECRAWL_RETRY_INITIAL_DELAY=2000    # Start with 2s delay
export FIRECRAWL_RETRY_MAX_DELAY=30000       # Maximum 30s delay
export FIRECRAWL_RETRY_BACKOFF_FACTOR=3      # More aggressive backoff

# Optional credit monitoring
export FIRECRAWL_CREDIT_WARNING_THRESHOLD=2000    # Warning at 2000 credits
export FIRECRAWL_CREDIT_CRITICAL_THRESHOLD=500    # Critical at 500 credits

Para instancia autohospedada:

# Required for self-hosted
export FIRECRAWL_API_URL=https://firecrawl.your-domain.com

# Optional authentication for self-hosted
export FIRECRAWL_API_KEY=your-api-key  # If your instance requires auth

# Custom retry configuration
export FIRECRAWL_RETRY_MAX_ATTEMPTS=10
export FIRECRAWL_RETRY_INITIAL_DELAY=500     # Start with faster retries

Uso con Claude Desktop

Agregue esto a su 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"
      }
    }
  }
}

Configuración del sistema

El servidor incluye varios parámetros configurables mediante variables de entorno. Estos son los valores predeterminados si no se configuran:

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, // Critical alert when credit usage reaches this level
  },
};

Estas configuraciones controlan:

1. Comportamiento de reintento

   • Reintenta automáticamente las solicitudes fallidas debido a los límites de velocidad

   • Utiliza un retroceso exponencial para evitar saturar la API

   • Ejemplo: Con la configuración predeterminada, se realizarán reintentos en:

     • 1er reintento: 1 segundo de retraso

     • 2.º reintento: 2 segundos de retraso

     • 3.er reintento: 4 segundos de retraso (limitado a maxDelay)

2. Monitoreo del uso del crédito

   • Realiza un seguimiento del consumo de créditos API para el uso de API en la nube

   • Proporciona advertencias en umbrales específicos

   • Ayuda a prevenir interrupciones inesperadas del servicio

   • Ejemplo: Con configuración predeterminada:

     • Advertencia: quedan 1000 créditos

     • Alerta crítica cuando quedan 100 créditos

Limitación de velocidad y procesamiento por lotes

El servidor utiliza las capacidades de procesamiento por lotes y limitación de velocidad integradas de FireCrawl:

• Manejo automático del límite de velocidad con retroceso exponencial

• Procesamiento paralelo eficiente para operaciones por lotes

• Colas y limitación de solicitudes inteligentes

• Reintentos automáticos para errores transitorios

Herramientas disponibles

1. Herramienta de raspado ( firecrawl_scrape )

Extraiga contenido de una única URL con opciones avanzadas.

{
  "name": "firecrawl_scrape",
  "arguments": {
    "url": "https://example.com",
    "formats": ["markdown"],
    "onlyMainContent": true,
    "waitFor": 1000,
    "timeout": 30000,
    "mobile": false,
    "includeTags": ["article", "main"],
    "excludeTags": ["nav", "footer"],
    "skipTlsVerification": false
  }
}

2. Herramienta de raspado por lotes ( firecrawl_batch_scrape )

Extraiga múltiples URL de manera eficiente con limitación de velocidad integrada y procesamiento paralelo.

{
  "name": "firecrawl_batch_scrape",
  "arguments": {
    "urls": ["https://example1.com", "https://example2.com"],
    "options": {
      "formats": ["markdown"],
      "onlyMainContent": true
    }
  }
}

La respuesta incluye el ID de la operación para verificar el estado:

{
  "content": [
    {
      "type": "text",
      "text": "Batch operation queued with ID: batch_1. Use firecrawl_check_batch_status to check progress."
    }
  ],
  "isError": false
}

3. Verificar el estado del lote ( firecrawl_check_batch_status )

Comprobar el estado de una operación por lotes.

{
  "name": "firecrawl_check_batch_status",
  "arguments": {
    "id": "batch_1"
  }
}

4. Herramienta de búsqueda ( firecrawl_search )

Busque en la web y, opcionalmente, extraiga contenido de los resultados de búsqueda.

{
  "name": "firecrawl_search",
  "arguments": {
    "query": "your search query",
    "limit": 5,
    "lang": "en",
    "country": "us",
    "scrapeOptions": {
      "formats": ["markdown"],
      "onlyMainContent": true
    }
  }
}

5. Herramienta de rastreo ( firecrawl_crawl )

Inicie un rastreo asincrónico con opciones avanzadas.

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

6. Herramienta de extracción ( firecrawl_extract )

Extraiga información estructurada de páginas web con las capacidades de LLM. Compatible con IA en la nube y extracción de LLM autoalojada.

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

Ejemplo de respuesta:

{
  "content": [
    {
      "type": "text",
      "text": {
        "name": "Example Product",
        "price": 99.99,
        "description": "This is an example product description"
      }
    }
  ],
  "isError": false
}

Opciones de la herramienta de extracción:

• urls : Matriz de URL de las que extraer información

• prompt : Aviso personalizado para la extracción de LLM

• systemPrompt : mensaje del sistema para guiar al LLM

• schema : esquema JSON para extracción de datos estructurados

• allowExternalLinks : Permitir la extracción de enlaces externos

• enableWebSearch : Habilita la búsqueda web para contexto adicional

• includeSubdomains : Incluir subdominios en la extracción

Al usar una instancia autoalojada, la extracción usará el LLM configurado. Para la API en la nube, se usa el servicio LLM administrado de FireCrawl.

Sistema de registro

El servidor incluye un registro completo:

• Estado y progreso de la operación

• Métricas de rendimiento

• Monitoreo del uso del crédito

• Seguimiento del límite de velocidad

• Condiciones de error

Ejemplos de mensajes de registro:

[INFO] FireCrawl MCP Server initialized successfully
[INFO] Starting scrape for URL: https://example.com
[INFO] Batch operation queued with ID: batch_1
[WARNING] Credit usage has reached warning threshold
[ERROR] Rate limit exceeded, retrying in 2s...

Manejo de errores

El servidor proporciona un manejo robusto de errores:

• Reintentos automáticos para errores transitorios

• Manejo del límite de velocidad con retroceso

• Mensajes de error detallados

• Advertencias sobre el uso del crédito

• Resiliencia de la red

Ejemplo de respuesta de error:

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

Desarrollo

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

Contribuyendo

1. Bifurcar el repositorio

2. Crea tu rama de funciones

3. Ejecutar pruebas: npm test

4. Enviar una solicitud de extracción

Licencia

Licencia MIT: consulte el archivo de LICENCIA para obtener más detalles