Firecrawl MCP

Servidor MCP de Firecrawl

Un servidor de Protocolo de Contexto de Modelo (MCP) que trae Firecrawl a agentes de IA compatibles con MCP — busca, extrae e interactúa con la web en vivo para obtener contexto limpio y listo para agentes.

¡Muchas gracias a @vrknetha, @knacklabs por la implementación inicial!

Características

• Busca en la web y obtén el contenido completo de la página
• Extrae cualquier URL en datos limpios y estructurados
• Interactúa con páginas — haz clic, navega y opera
• Investigación profunda con agente autónomo
• Reintentos automáticos y limitación de velocidad
• Soporte en la nube y autohospedado
• Soporte SSE

Prueba nuestro Servidor MCP en el playground de MCP.so o en Klavis AI.

Instalación

MCP Alojado (nivel gratuito sin clave)

Conéctate al servidor remoto alojado sin configuración:

https://mcp.firecrawl.dev/v2/mcp

En el nivel gratuito sin clave, scrape, search y interact funcionan sin una clave API (con límite de velocidad). Otras herramientas como crawl, map, agent y extract aún necesitan una clave.

Prefiere una clave API u OAuth siempre que el humano pueda registrarse. Desbloquea el conjunto completo de herramientas y límites más altos. Con una clave, usa:

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

Consulta la documentación del servidor MCP y la guía de incorporación de agentes para detalles de configuración.

Endpoint solo de búsqueda

También se aloja una superficie de solo lectura y solo búsqueda en:

https://mcp.firecrawl.dev/v2/mcp-search

Expone un conjunto fijo de seis herramientas de solo lectura: firecrawl_search y las cinco herramientas firecrawl_research_*. No realiza obtención de contenido de página y tiene su propia identidad OAuth; el endpoint completo anterior no se modifica. Consulta docs/search-profile.md para el contrato completo.

Ejecutar con npx

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

Instalación Manual

npm install -g firecrawl-mcp

Ejecutar en Cursor

Configurando Cursor 🖥️ Nota: Requiere Cursor versión 0.45.6+ Para las instrucciones de configuración más actualizadas, consulta la documentación oficial de Cursor sobre la configuración de servidores MCP: Guía de Configuración del Servidor MCP de Cursor

Para configurar Firecrawl MCP en Cursor v0.48.6

1. Abre la Configuración de Cursor
2. Ve a Funciones > Servidores MCP
3. Haz clic en "+ Agregar nuevo servidor MCP global"
4. Ingresa el siguiente código:

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

Para configurar Firecrawl MCP en Cursor v0.45.6

1. Abre la Configuración de Cursor
2. Ve a Funciones > Servidores MCP
3. Haz clic en "+ Agregar Nuevo Servidor MCP"
4. Ingresa lo siguiente:
   • Nombre: "firecrawl-mcp" (o tu nombre preferido)
   • Tipo: "command"
   • Comando: env FIRECRAWL_API_KEY=your-api-key npx -y firecrawl-mcp

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

Reemplaza your-api-key con tu clave API de Firecrawl. Si aún no tienes una, puedes crear una cuenta y obtenerla desde https://www.firecrawl.dev/app/api-keys

Después de agregar, actualiza la lista de servidores MCP para ver las nuevas herramientas. El Agente Compositor usará automáticamente Firecrawl MCP cuando sea apropiado, pero puedes solicitarlo explícitamente describiendo tus necesidades de extracción web. Accede al Compositor mediante Comando+L (Mac), selecciona "Agente" junto al botón de enviar e ingresa tu consulta.

Ejecutar en Windsurf

Agrega esto a tu ./codeium/windsurf/model_config.json:

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

Ejecutar con Modo Local HTTP Transmisible

Para ejecutar el servidor usando HTTP Transmisible localmente en lugar del transporte stdio predeterminado:

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

Usa la url: http://localhost:3000/mcp

Instalar vía Smithery (Legado)

Para instalar Firecrawl para Claude Desktop automáticamente vía Smithery:

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

Ejecutar en VS Code

Para instalación con un clic, haz clic en uno de los botones de instalación a continuación...

Para instalación manual, agrega el siguiente bloque JSON a tu archivo de Configuración de Usuario (JSON) en VS Code. Puedes hacer esto presionando Ctrl + Shift + P y escribiendo Preferences: Open User Settings (JSON).

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

Opcionalmente, puedes agregarlo a un archivo llamado .vscode/mcp.json en tu espacio de trabajo. Esto te permitirá compartir la configuración con otros:

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

Configuración

Variables de Entorno

Requerido para API en la Nube

• FIRECRAWL_API_KEY: Tu clave API de Firecrawl
  • Requerido cuando se usa la API en la nube (predeterminado)
  • Opcional cuando se usa una instancia autohospedada con FIRECRAWL_API_URL
• FIRECRAWL_API_URL (Opcional): Endpoint API personalizado para instancias autohospedadas
  • Ejemplo: https://firecrawl.your-domain.com
  • Si no se proporciona, se usará la API en la nube (requiere clave API)

OAuth MCP (Tokens de acceso Bearer)

Firecrawl alojado puede emitir tokens de acceso OAuth (fco_…) a través del servidor de autorización en firecrawl.dev. Este servidor MCP reenvía la credencial que resuelva a la API de Firecrawl como Authorization: Bearer ….

• Transportes de flujo HTTP (CLOUD_SERVICE=true, HTTP_STREAMABLE_SERVER=true o SSE_LOCAL=true): Los clientes deben enviar Authorization: Bearer <fco_access_token> en las solicitudes MCP. Un token bearer OAuth tiene prioridad sobre x-firecrawl-api-key / x-api-key cuando ambos están presentes.
• stdio: Usa FIRECRAWL_OAUTH_TOKEN para un token de acceso estático, o continúa usando FIRECRAWL_API_KEY para una clave API.

Usa solo tokens de acceso (fco_…). Los tokens de actualización (fcr_…) deben intercambiarse en el endpoint de token, no pasarse a la API de extracción/búsqueda.

Superficie solo de búsqueda (alojada)

En modo alojado (CLOUD_SERVICE=true) una segunda instancia en proceso sirve el endpoint solo de búsqueda. El servicio empaquetado tiene un contrato de despliegue fijo: nginx enruta /v2/mcp-search a la instancia en el puerto local 3001, y el identificador de recurso protegido OAuth es https://mcp.firecrawl.dev/v2/mcp-search.

FIRECRAWL_MCP_SEARCH_ENABLED (predeterminado true) es el interruptor operativo soportado; configúralo en false para evitar que la instancia de búsqueda se inicie. El proceso Node también acepta FIRECRAWL_MCP_SEARCH_PORT, FIRECRAWL_MCP_SEARCH_ENDPOINT y FIRECRAWL_MCP_SEARCH_RESOURCE_URL para pruebas aisladas. Esas anulaciones no reconfiguran las rutas nginx empaquetadas ni la lista de permitidos del servidor de autorización y no deben usarse de forma independiente en el despliegue alojado.

La instancia de búsqueda requiere autenticación para cada solicitud (incluyendo tools/list) y rechaza tokens OAuth cuya audiencia no coincida con su propio recurso.

Ejemplos de Configuración

Para uso de API en la nube:

export FIRECRAWL_API_KEY=your-api-key

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

Uso con Claude Desktop

Agrega esto a tu claude_desktop_config.json:

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

Cómo Elegir una Herramienta

Usa esta guía para seleccionar la herramienta adecuada para tu tarea:

• Si conoces la URL exacta que deseas: usa scrape (con formato JSON para datos estructurados)
• Si tienes múltiples URLs conocidas: llama a scrape para cada URL. Si necesitas específicamente una operación de API por lotes, usa el endpoint batch de la API de Firecrawl fuera de MCP.
• Si necesitas descubrir URLs en un sitio: usa map
• Si deseas buscar información en la web: usa search
• Si necesitas investigación compleja a través de múltiples fuentes desconocidas: usa agent
• Si deseas analizar un sitio completo o una sección: usa crawl (¡con límites!)
• Si necesitas automatización interactiva del navegador (clic, escribir, navegar): usa interact con una URL para una página nueva, o scrape + interact cuando ya hayas extraído la página o necesites un control de extracción más estricto

Tabla de Referencia Rápida

Herramienta	Ideal para	Devuelve
scrape	Contenido de una sola página	JSON (preferido) o markdown
interact	Interactuar con una URL o página extraída	Resultado de ejecución + scrapeId para modo URL
map	Descubrir URLs en un sitio	URL[]
crawl	Extracción multipágina (con límites)	estado/datos finales del rastreo después de sondeo interno
parse	Archivos y refs de carga alojadas	markdown, JSON o salida de documento
extract	Extracción estructurada de URLs	Datos estructurados JSON
search	Búsqueda web de información	results[]
agent	Investigación compleja multifuente	JSON (datos estructurados)
monitor	Verificaciones recurrentes de páginas	metadatos y diferencias de monitor/check
research	Investigación de papers y repositorios de GitHub	resultados de investigación y coincidencias de repo

Guía de Selección de Formato

Al usar scrape, elige el formato correcto:

• Formato JSON (recomendado para la mayoría de los casos): Úsalo cuando necesites datos específicos de una página. Define un esquema basado en lo que necesitas extraer. Esto mantiene las respuestas pequeñas y evita el desbordamiento de la ventana de contexto.
• Formato Markdown (usar con moderación): Solo cuando realmente necesites el contenido completo de la página, como leer un artículo completo para resumir o analizar la estructura de la página.

Herramientas Disponibles

1. Herramienta Scrape (firecrawl_scrape)

Extrae contenido de una sola URL con opciones avanzadas.

Ideal para:

• Extracción de contenido de una sola página, cuando sabes exactamente qué página contiene la información.

No recomendado para:

• Extraer contenido de múltiples páginas (usa llamadas repetidas a scrape para URLs conocidas, o map + scrape para descubrir URLs primero, o crawl para contenido completo de página)
• Cuando no estás seguro de qué página contiene la información (usa search)

Errores comunes:

• Pasar una lista de URLs a una sola llamada de scrape. Llama a scrape una vez por URL en MCP. Si necesitas específicamente una operación de API por lotes, usa el endpoint batch de la API de Firecrawl fuera de MCP.
• Usar formato markdown por defecto (usa formato JSON para extraer solo lo que necesitas).

Eligiendo el formato correcto:

• Formato JSON (preferido): Para la mayoría de los casos de uso, usa formato JSON con un esquema para extraer solo los datos específicos necesarios. Esto mantiene las respuestas enfocadas y previene el desbordamiento de la ventana de contexto.
• Formato Markdown: Solo cuando la tarea realmente requiera el contenido completo de la página (ej., resumir un artículo completo, analizar la estructura de la página).

Ejemplo de Prompt:

"Obtén los detalles del producto de https://example.com/product."

Ejemplo de Uso (formato JSON - preferido):

{
  "name": "firecrawl_scrape",
  "arguments": {
    "url": "https://example.com/product",
    "formats": [
      {
        "type": "json",
        "prompt": "Extract the product information",
        "schema": {
          "type": "object",
          "properties": {
            "name": { "type": "string" },
            "price": { "type": "number" },
            "description": { "type": "string" }
          },
          "required": ["name", "price"]
        }
      }
    ]
  }
}

Ejemplo de Uso (formato markdown - cuando se necesita contenido completo):

{
  "name": "firecrawl_scrape",
  "arguments": {
    "url": "https://example.com/article",
    "formats": ["markdown"],
    "onlyMainContent": true
  }
}

Ejemplo de Uso (formato branding - extraer identidad de marca):

{
  "name": "firecrawl_scrape",
  "arguments": {
    "url": "https://example.com",
    "formats": ["branding"]
  }
}

Formato Branding: Extrae identidad de marca integral (colores, fuentes, tipografía, espaciado, logo, componentes UI) para análisis de diseño o replicación de estilo. Privacidad: Configura redactPII: true para devolver contenido con información de identificación personal redactada.

Devuelve:

• Datos estructurados JSON, markdown, perfil de marca u otros formatos según lo especificado.

2. Herramienta Map (firecrawl_map)

Mapea un sitio web para descubrir todas las URLs indexadas en el sitio.

Ideal para:

• Descubrir URLs en un sitio web antes de decidir qué extraer
• Encontrar secciones específicas de un sitio web

No recomendado para:

• Cuando ya sabes qué URL específica necesitas (usa scrape)
• Cuando necesitas el contenido de las páginas (usa scrape después de mapear)

Errores comunes:

• Usar crawl para descubrir URLs en lugar de map

Ejemplo de Prompt:

"Lista todas las URLs en example.com."

Ejemplo de Uso:

{
  "name": "firecrawl_map",
  "arguments": {
    "url": "https://example.com"
  }
}

Devuelve:

• Array de URLs encontradas en el sitio

3. Herramienta Search (firecrawl_search)

Busca en la web y opcionalmente extrae contenido de los resultados de búsqueda.

Ideal para:

• Encontrar información específica en múltiples sitios web, cuando no sabes qué sitio web tiene la información.
• Cuando necesitas el contenido más relevante para una consulta

No recomendado para:

• Cuando ya sabes qué sitio web extraer (usa scrape)
• Cuando necesitas cobertura completa de un solo sitio web (usa map o crawl)

Errores comunes:

• Usar crawl o map para preguntas abiertas (usa search en su lugar)

Ejemplo de Uso:

{
  "name": "firecrawl_search",
  "arguments": {
    "query": "latest AI research papers 2023",
    "highlights": true,
    "limit": 5,
    "lang": "en",
    "country": "us",
    "scrapeOptions": {
      "formats": ["markdown"],
      "onlyMainContent": true,
      "redactPII": true
    }
  }
}

Establezca highlights en true para solicitar fragmentos relevantes a la consulta o false para conservar los fragmentos de búsqueda originales. Omítalo para usar el comportamiento predeterminado de la API.

Devuelve:

• Matriz de resultados de búsqueda (con contenido extraído opcional), más un campo id. Pase ese id a firecrawl_search_feedback después de haber usado los resultados para reembolsar 1 crédito (la búsqueda cuesta 2) y mejorar la calidad de búsqueda.

Ejemplo de prompt:

"Encuentra los últimos artículos de investigación sobre IA publicados en 2023."

3b. Herramienta de retroalimentación de búsqueda (firecrawl_search_feedback)

Envía retroalimentación estructurada sobre un resultado previo de firecrawl_search. La primera retroalimentación por ID de búsqueda reembolsa 1 crédito y mejora la calidad de búsqueda de Firecrawl. Idempotente por ID de búsqueda.

Llame a esto después de cada búsqueda que realmente use (o que no haya ayudado). La retroalimentación negativa/parcial con missingContent es tan valiosa como la positiva.

Exclusión voluntaria: establezca FIRECRAWL_NO_SEARCH_FEEDBACK=1 (o FIRECRAWL_DISABLE_SEARCH_FEEDBACK=1) en el entorno al iniciar el servidor MCP. La herramienta firecrawl_search_feedback no se registrará, por lo que los agentes no pueden llamarla. Los administradores de equipo también pueden deshabilitar la retroalimentación del lado del servidor; en ese caso, la herramienta se registra pero siempre devuelve feedbackErrorCode: "TEAM_OPTED_OUT".

Campo más importante: missingContent. Es una matriz de piezas específicas de contenido que el agente esperaba encontrar pero no encontró. Una entrada por tema faltante: estos se agregan entre equipos y nos indican qué indexar a continuación.

Límite diario de reembolso (por equipo, por día UTC, predeterminado 100 créditos). Una vez que el creditsRefundedToday de un equipo alcanza dailyRefundCap, los envíos posteriores aún registran la retroalimentación pero ya no reembolsan créditos. La respuesta establece dailyCapReached: true. Los agentes deben dejar de llamar a esta herramienta durante el resto del día UTC cuando vean esa bandera.

Ejemplo de uso:

{
  "name": "firecrawl_search_feedback",
  "arguments": {
    "searchId": "0193f6c5-1234-7890-abcd-1234567890ab",
    "rating": "good",
    "valuableSources": [
      {
        "url": "https://docs.firecrawl.dev/features/search",
        "reason": "Most up-to-date description of /search."
      }
    ],
    "missingContent": [
      {
        "topic": "Pricing for the search endpoint",
        "description": "No pricing tier table for /search specifically."
      },
      { "topic": "Per-team rate limits" }
    ],
    "querySuggestions": "Boost docs.firecrawl.dev for queries that mention 'firecrawl'"
  }
}

Devuelve:

• JSON { success, feedbackId, creditsRefunded, alreadySubmitted? }.

3c. Herramienta de retroalimentación genérica (firecrawl_feedback)

Envía retroalimentación estructurada para un trabajo de endpoint v2 completado a través de /v2/feedback. Use esto para retroalimentación a nivel de endpoint en trabajos de scrape, parse, map o search. Para la calidad de los resultados de búsqueda específicamente, prefiera firecrawl_search_feedback porque incluye orientación específica de búsqueda.

Mantenga la retroalimentación concisa: use códigos de problema, etiquetas, notas breves, URLs, números de página y objetos de metadatos pequeños. No incluya resultados sin procesar de extracción/análisis.

Exclusión voluntaria: establezca FIRECRAWL_NO_ENDPOINT_FEEDBACK=1 (o FIRECRAWL_DISABLE_ENDPOINT_FEEDBACK=1) en el entorno al iniciar el servidor MCP. La herramienta firecrawl_feedback no se registrará, por lo que los agentes no pueden llamarla.

Ejemplo de uso:

{
  "name": "firecrawl_feedback",
  "arguments": {
    "endpoint": "scrape",
    "jobId": "0193f6c5-1234-7890-abcd-1234567890ab",
    "rating": "partial",
    "issues": ["missing_markdown"],
    "tags": ["docs"],
    "note": "The pricing table was missing from the markdown output.",
    "url": "https://example.com/pricing",
    "pageNumbers": [1],
    "metadata": {
      "format": "markdown"
    }
  }
}

Devuelve:

• JSON { success, feedbackId, creditsRefunded, creditsRefundedToday?, dailyRefundCap?, dailyCapReached?, alreadySubmitted?, warning? }.

4. Herramienta de rastreo (firecrawl_crawl)

Inicia un trabajo de rastreo, sondea hasta que alcanza un estado terminal y devuelve el estado/datos finales del rastreo.

Ideal para:

• Extraer contenido de múltiples páginas relacionadas, cuando necesita una cobertura completa.

No recomendado para:

• Extraer contenido de una sola página (use extracción)
• Cuando los límites de tokens son una preocupación (use mapa + extracción para un control más estricto)
• Cuando necesita resultados rápidos (el rastreo puede ser lento)

Advertencia: Las respuestas de rastreo pueden ser muy grandes y pueden exceder los límites de tokens. Limite la profundidad de rastreo y el número de páginas, o use mapa + extracción para un control más estricto.

Errores comunes:

• Establecer limit o maxDiscoveryDepth demasiado alto (causa desbordamiento de tokens)
• Usar rastreo para una sola página (use extracción en su lugar)

Ejemplo de prompt:

"Obtén todas las publicaciones del blog de los dos primeros niveles de example.com/blog."

Ejemplo de uso:

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

Devuelve:

• Estado y datos finales del rastreo después del sondeo interno, incluyendo id, status, completed, total, creditsUsed, expiresAt, next y data. Use el id devuelto con firecrawl_check_crawl_status si necesita volver a verificar el trabajo más tarde.

5. Verificar estado del rastreo (firecrawl_check_crawl_status)

Verifique el estado y los resultados de un trabajo de rastreo existente por ID.

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

Devuelve:

• La respuesta incluye el estado del trabajo de rastreo:

6. Herramienta de análisis (firecrawl_parse)

Analice archivos locales o referencias de carga alojadas con el endpoint /v2/parse de Firecrawl.

Ideal para: PDFs, documentos de Word, hojas de cálculo, archivos HTML y otros documentos que necesitan salida en markdown o JSON estructurado. MCP alojado admite un flujo de carga-referencia de dos pasos; las lecturas directas de archivos locales requieren un FIRECRAWL_API_URL autohospedado.

No recomendado para: URLs remotas (use extracción), múltiples archivos en una llamada (llame a análisis una vez por archivo) o acciones solo de navegador como capturas de pantalla y clics.

Flujo MCP alojado: MCP alojado no puede leer directamente el sistema de archivos del llamante. Llame a firecrawl_parse con filePath para recibir un comando de carga de corta duración y nextToolCall, cargue el archivo localmente, luego llame a firecrawl_parse nuevamente con el uploadRef devuelto. Acuñar la URL de carga alojada requiere autenticación de Firecrawl o elegibilidad sin clave. En modo npx firecrawl-mcp local, el análisis directo de archivos actualmente requiere FIRECRAWL_API_URL apuntando a una API de Firecrawl autohospedada; un servidor local simple solo con clave API en la nube no puede leer y cargar archivos a través de esta herramienta.

Ejemplo de uso:

{
  "name": "firecrawl_parse",
  "arguments": {
    "filePath": "/absolute/path/to/document.pdf",
    "formats": ["markdown"],
    "parsers": ["pdf"],
    "zeroDataRetention": true
  }
}

Devuelve: Contenido del documento analizado o instrucciones de carga alojada con un nextToolCall.

7. Herramienta de extracción (firecrawl_extract)

Extraiga información estructurada de páginas web utilizando capacidades de LLM. Admite tanto IA en la nube como extracción LLM autohospedada.

Ideal para:

• Extraer datos estructurados específicos como precios, nombres, detalles.

No recomendado para:

• Cuando necesita el contenido completo de una página (use extracción)
• Cuando no está buscando datos estructurados específicos

Argumentos:

• urls: Matriz de URLs de las que extraer información
• prompt: Prompt personalizado para la extracción LLM
• systemPrompt: Prompt del sistema para guiar al LLM
• schema: Esquema JSON para la extracción de datos estructurados
• allowExternalLinks: Permitir extracción de enlaces externos
• enableWebSearch: Habilitar búsqueda web para contexto adicional
• includeSubdomains: Incluir subdominios en la extracción

Al usar una instancia autohospedada, la extracción usará su LLM configurado. Para la API en la nube, utiliza el servicio LLM administrado de Firecrawl. Ejemplo de prompt:

"Extrae el nombre del producto, precio y descripción de estas páginas de productos."

Ejemplo de uso:

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

Devuelve:

• Datos estructurados extraídos según lo definido por su esquema

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

8. Herramienta de agente (firecrawl_agent)

Agente de investigación web autónomo. Esta es una capa de agente de IA separada que navega por internet de forma independiente, busca información, navega a través de páginas y extrae datos estructurados según su consulta.

Cómo funciona:

El agente realiza búsquedas web, sigue enlaces, lee páginas y recopila datos de forma autónoma. Esto se ejecuta de forma asíncrona: devuelve un ID de trabajo inmediatamente, y usted sondea firecrawl_agent_status para verificar cuándo se completa y recuperar los resultados.

Flujo de trabajo asíncrono:

1. Llame a firecrawl_agent con su prompt/esquema → devuelve ID de trabajo
2. Haga otro trabajo mientras el agente investiga (puede tomar minutos para consultas complejas)
3. Sondee firecrawl_agent_status con el ID de trabajo para verificar el progreso
4. Cuando el estado es "completed", la respuesta incluye los datos extraídos

Ideal para:

• Tareas de investigación complejas donde no conoce las URLs exactas
• Recopilación de datos de múltiples fuentes
• Encontrar información dispersa en la web
• Tareas donde puede hacer otro trabajo mientras espera los resultados

No recomendado para:

• Extracción simple de una sola página donde conoce la URL (use extracción con formato JSON - más rápido y barato)

Argumentos:

• prompt: Descripción en lenguaje natural de los datos que desea (obligatorio, máximo 10,000 caracteres)
• urls: Matriz opcional de URLs para enfocar al agente en páginas específicas
• schema: Esquema JSON opcional para salida estructurada

Ejemplo de prompt:

"Encuentra los fundadores de Firecrawl y sus antecedentes"

Ejemplo de uso (iniciar agente, luego sondear resultados):

{
  "name": "firecrawl_agent",
  "arguments": {
    "prompt": "Find the top 5 AI startups founded in 2024 and their funding amounts",
    "schema": {
      "type": "object",
      "properties": {
        "startups": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": { "type": "string" },
              "funding": { "type": "string" },
              "founded": { "type": "string" }
            }
          }
        }
      }
    }
  }
}

Luego sondee con firecrawl_agent_status usando el ID de trabajo devuelto.

Ejemplo de uso (con URLs - el agente se enfoca en páginas específicas):

{
  "name": "firecrawl_agent",
  "arguments": {
    "urls": ["https://docs.firecrawl.dev", "https://firecrawl.dev/pricing"],
    "prompt": "Compare the features and pricing information from these pages"
  }
}

Devuelve:

• ID de trabajo para verificación de estado. Use firecrawl_agent_status para sondear resultados.

9. Verificar estado del agente (firecrawl_agent_status)

Verifique el estado de un trabajo de agente y recupere los resultados cuando esté completo. Use esto para sondear resultados después de iniciar un agente.

Patrón de sondeo: La investigación del agente puede tomar minutos para consultas complejas. Sondee este endpoint periódicamente (por ejemplo, cada 10-30 segundos) hasta que el estado sea "completed" o "failed".

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

Estados posibles:

• processing: El agente todavía está investigando - vuelva a consultar más tarde
• completed: Investigación finalizada - la respuesta incluye los datos extraídos
• failed: Ocurrió un error

10. Herramienta de interacción (firecrawl_interact)

Interactúe con una URL nueva o con una página que ya fue abierta por firecrawl_scrape.

Ideal para: Hacer clic, escribir, navegar y extraer estado de páginas dinámicas sin restaurar las herramientas de navegador obsoletas.

Opciones de uso:

• Pase url para extraer y abrir una página para interacción en una llamada MCP.
• Pase scrapeId para continuar interactuando con una página extraída existente.
• Pase exactamente uno de url o scrapeId, más prompt o code.

Ejemplo de uso:

{
  "name": "firecrawl_interact",
  "arguments": {
    "url": "https://example.com",
    "prompt": "Click the pricing link and summarize the visible plans"
  }
}

Devuelve: Resultado de la interacción y, para el modo URL, el scrapeId derivado para seguimiento o limpieza.

11. Herramienta para detener interacción (firecrawl_interact_stop)

Detenga una sesión de interacción para una página extraída cuando haya terminado de interactuar.

{
  "name": "firecrawl_interact_stop",
  "arguments": {
    "scrapeId": "scrape-id-here"
  }
}

12. Herramientas de investigación (firecrawl_research_*)

Busque e inspeccione artículos y repositorios de GitHub a través de las herramientas MCP de investigación.

Herramientas de investigación disponibles:

• firecrawl_research_search_papers: buscar artículos de investigación.
• firecrawl_research_inspect_paper: inspeccionar un artículo.
• firecrawl_research_related_papers: encontrar artículos relacionados.
• firecrawl_research_read_paper: leer contenido del artículo.
• firecrawl_research_search_github: buscar repositorios de GitHub.

Ideal para: Revisión de literatura, búsqueda de artículos y flujos de trabajo de descubrimiento de repositorios donde el agente necesita una superficie de investigación enfocada en lugar de extracción web general.

13. Herramientas de monitoreo (firecrawl_monitor_*)

Cree y administre monitores de páginas recurrentes. Los monitores ejecutan extracciones o rastreos programados, comparan cada resultado con la última instantánea retenida y pueden notificar por webhook o correo electrónico.

Ideal para:

• Observar una página o unas pocas páginas a lo largo del tiempo
• Alertar sobre cambios significativos usando un objetivo en lenguaje sencillo
• Rastrear el historial de verificaciones y diferencias a nivel de página

Patrón de creación recomendado:

Use page o pages más goal. El servidor MCP construye la solicitud de monitor con un horario de 30 minutos y la API habilita el juicio de cambio significativo automáticamente.

El juicio de cambio significativo se ejecuta automáticamente cuando goal está configurado. Los webhooks de página exponen isMeaningful y judgment en eventos monitor.page.

Escriba los objetivos como instrucciones de monitor concisas de 2-3 oraciones. Diga qué debería activar una alerta, conserve cualquier alcance que el usuario haya dado e incluya exclusiones específicas de intención solo cuando sean obvias a partir de la solicitud. El ruido genérico como espacios en blanco, cambios solo de formato, IDs de solicitud, parámetros de seguimiento, metadatos genéricos y cromo de página no relacionado ya es manejado por el juez, así que no lo repita en cada objetivo. Si el usuario es vago, mantenga el objetivo amplio; si pide monitoreo amplio o "cualquier cambio", consérvelo. Si el usuario dice que no le importa algo, inclúyalo explícitamente.

{
  "name": "firecrawl_monitor_create",
  "arguments": {
    "page": "https://example.com/pricing",
    "goal": "Alert when pricing, packaging, or launch messaging changes."
  }
}

Múltiples páginas con webhooks:

{
  "name": "firecrawl_monitor_create",
  "arguments": {
    "pages": ["https://example.com/pricing", "https://example.com/changelog"],
    "goal": "Alert when pricing, packaging, or launch messaging changes.",
    "webhookUrl": "https://example.com/webhooks/firecrawl"
  }
}

Solicitudes de creación avanzadas:

Pase body cuando necesite objetivos de rastreo, seguimiento de cambios JSON, retención personalizada o control explícito de judgeEnabled.

{
  "name": "firecrawl_monitor_create",
  "arguments": {
    "body": {
      "name": "Docs monitor",
      "schedule": { "text": "hourly", "timezone": "UTC" },
      "goal": "Alert when docs pages add, remove, or materially change API behavior.",
      "targets": [{ "type": "crawl", "url": "https://example.com/docs" }]
    }
  }
}

Otras herramientas de monitor:

• firecrawl_monitor_list: listar monitores.
• firecrawl_monitor_get: obtener un monitor.
• firecrawl_monitor_update: actualizar campos incluyendo goal, judgeEnabled, webhook y notification.
• firecrawl_monitor_run: activar una verificación ahora.
• firecrawl_monitor_delete: eliminar un monitor (destructivo; solo llamar cuando el usuario tenga la intención de eliminarlo).
• firecrawl_monitor_checks: listar verificaciones, opcionalmente filtradas por estado.
• firecrawl_monitor_check: obtener resultados a nivel de página, incluyendo diff, snapshot, judgment.meaningful y judgment.meaningfulChanges.

Sistema de Registro

El servidor incluye un registro completo:

• Estado y progreso de las operaciones
• Métricas de rendimiento
• Seguimiento de límites de tasa
• Condiciones de error

Ejemplo de mensajes de registro:

[INFO] Firecrawl MCP Server initialized successfully
[INFO] Starting scrape for URL: https://example.com
[ERROR] Rate limit exceeded

Manejo de Errores

El servidor proporciona un manejo de errores robusto:

• Errores de límite de tasa de la API expuestos al cliente MCP
• Mensajes de error detallados
• Resiliencia de red

Ejemplo de respuesta de error:

{
  "content": [
    {
      "type": "text",
      "text": "Error: Rate limit exceeded"
    }
  ],
  "isError": true
}

Desarrollo

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

Contribuciones

1. Bifurcar el repositorio
2. Crear tu rama de funcionalidad
3. Ejecutar pruebas: npm test
4. Enviar una solicitud de extracción

Agradecimientos a los colaboradores

¡Gracias a @vrknetha, @cawstudios por la implementación inicial!

Gracias a MCP.so y Klavis AI por el alojamiento y a @gstarwd, @xiangkaiz y @zihaolin96 por integrar nuestro servidor.

Licencia

Licencia MIT - consulta el archivo LICENSE para más detalles