Firecrawl

Servidor MCP de Firecrawl

Un servidor de Model Context Protocol (MCP) que lleva 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
• Busca en un índice creado para agentes de programación: issues de GitHub, pull requests fusionados, READMEs y documentación
• 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 autoalojado
• 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 parse funcionan sin clave de API (con límite de velocidad). Otras herramientas como crawl, map y agent aún necesitan una clave.

Prefiere OAuth o una clave de API siempre que la persona pueda registrarse. Desbloquea el conjunto completo de herramientas y límites más altos.

Para una conexión de cuenta interactiva, configura tu cliente MCP para usar esta URL de servidor. Este es un endpoint de MCP, no una página de navegador; usa el flujo de conexión de cuenta del cliente y no agregues una segunda entrada de servidor de Firecrawl al reconectar:

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

Para una conexión con clave de API (por ejemplo, una integración desatendida), mantén la URL del servidor como:

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

Luego configura el encabezado seguro o el ajuste de secreto del cliente con:

Authorization: Bearer <FIRECRAWL_API_KEY>

Nunca pongas una clave de API en la URL del servidor. Nunca pongas una clave de API en un chat de agente. Configúrala directamente en el cliente o en el gestor de secretos. Consulta la guía de configuración de MCP alojado y la guía de incorporación de agentes para instrucciones específicas del cliente.

Endpoint de solo 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 ninguna obtención de contenido de página y tiene su propia identidad OAuth; el endpoint completo anterior no cambia. Consulta docs/search-profile.md para el contrato completo.

Ejecución con npx

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

Instalación manual

npm install -g firecrawl-mcp

Ejecución en Cursor

Configurando Cursor 🖥️ Nota: Requiere la versión 0.45.6+ de Cursor Para obtener 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 Features > MCP Servers
3. Haz clic en "+ Add new global MCP server"
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 Features > MCP Servers
3. Haz clic en "+ Add New MCP Server"
4. Ingresa lo siguiente:
   • Nombre: "firecrawl-mcp" (o el nombre que prefieras)
   • Tipo: "command"
   • Comando: env FIRECRAWL_API_KEY=your-api-key npx -y firecrawl-mcp

Si usas 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 de API de Firecrawl. Si aún no tienes una, puedes crear una cuenta y obtenerla en https://www.firecrawl.dev/app/api-keys

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

Ejecución 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"
      }
    }
  }
}

Ejecución con modo local Streamable HTTP

Para ejecutar el servidor usando Streamable HTTP 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

Instalación mediante Smithery (heredado)

Para instalar Firecrawl para Claude Desktop automáticamente mediante Smithery:

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

Ejecución en VS Code

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

Para la instalación manual, agrega el siguiente bloque JSON a tu archivo de User Settings (JSON) en VS Code. Puedes hacerlo 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

Requeridas para la API en la nube

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

MCP OAuth (tokens de acceso Bearer)

Firecrawl alojado puede emitir tokens de acceso OAuth (fco_…) mediante el 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 sigue usando FIRECRAWL_API_KEY para una clave de API.

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

Superficie de solo búsqueda (alojada)

En el modo alojado (CLOUD_SERVICE=true), una segunda instancia en proceso sirve el endpoint de solo búsqueda. El servicio incluido tiene un contrato de implementación 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 compatible; configúralo en false para evitar que la instancia de búsqueda se inicie. El proceso de 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 incluidas ni la lista de permitidos del servidor de autorización y no deben usarse de forma independiente en la implementación alojada.

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

Ejemplos de configuración

Para uso de la API en la nube:

export FIRECRAWL_API_KEY=your-api-key

Para instancia autoalojada:

# 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 quieres: usa scrape (con formato JSON para datos estructurados)
• Si tienes varias URL conocidas: llama a scrape para cada URL. Si necesitas específicamente una operación masiva de API, usa el endpoint de lote de la API de Firecrawl fuera de MCP.
• Si necesitas descubrir URL en un sitio: usa map
• Si quieres buscar información en la web: usa search
• Si tienes una pregunta de programación (una biblioteca, un contrato de API, un mensaje de error, un error conocido): usa developer search
• Si necesitas artículos científicos (literatura biomédica, de ciencias de la vida, clínica o de arXiv): usa research tools — buscan resúmenes y texto completo de artículos. search con categories: ["research"] es algo diferente: un filtro de sitios web sobre resultados web ordinarios.
• Si necesitas investigación compleja en múltiples fuentes desconocidas: usa agent
• Si quieres analizar un sitio o sección completo: usa crawl (¡con límites!)
• Si necesitas automatización interactiva del navegador (hacer 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	Mejor 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 URL en un sitio	URL[]
crawl	Extracción de varias páginas (con límites)	estado/datos finales del rastreo después del sondeo interno
parse	Archivos y referencias de carga alojadas	markdown, JSON o salida de documento
search	Búsqueda web de información	results[]
developer	Preguntas de programación sobre fuentes de desarrolladores	results[] con pasajes
agent	Investigación compleja de múltiples fuentes	JSON (datos estructurados)
monitor	Comprobaciones recurrentes de páginas	metadatos y diferencias de monitor/check
research	Investigación de artículos y repositorios de GitHub	resultados de investigación y coincidencias de repositorios

Guía de selección de formato

Al usar scrape, elige el formato adecuado:

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

Herramientas disponibles

1. Herramienta Scrape (firecrawl_scrape)

Extrae contenido de una sola URL con opciones avanzadas.

Mejor para:

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

No recomendada para:

• Extraer contenido de varias páginas (usa llamadas repetidas de scrape para URL conocidas, o map + scrape para descubrir URL 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 URL a una sola llamada de scrape. Llama a scrape una vez por URL en MCP. Si necesitas específicamente una operación masiva de API, usa el endpoint de lote de la API de Firecrawl fuera de MCP.
• Usar el formato markdown por defecto (usa el formato JSON para extraer solo lo que necesitas).

Elegir el formato adecuado:

• Formato JSON (preferido): Para la mayoría de los casos de uso, usa el formato JSON con un esquema para extraer solo los datos específicos necesarios. Esto mantiene las respuestas enfocadas y evita el desbordamiento de la ventana de contexto.
• Formato Markdown: Solo cuando la tarea realmente requiera el contenido completo de la página (por ejemplo, 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 el contenido completo):

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

Ejemplo de uso (formato de marca - extraer identidad de marca):

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

Formato de marca: Extrae la identidad de marca completa (colores, fuentes, tipografía, espaciado, logotipo, componentes de 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 se especifique.

2. Herramienta Map (firecrawl_map)

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

Mejor 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 del mapeo)

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:

• Matriz de URLs encontradas en el sitio

3. Herramienta de búsqueda (firecrawl_search)

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

Mejor para:

• Encontrar información específica en múltiples sitios web, cuando no sabes qué sitio 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": "remote work stipend policies at tech companies",
    "highlights": true,
    "limit": 5,
    "lang": "en",
    "country": "us",
    "scrapeOptions": {
      "formats": ["markdown"],
      "onlyMainContent": true,
      "redactPII": true
    }
  }
}

Establece highlights a true para solicitar resaltados relevantes a la consulta o false para mantener los fragmentos de búsqueda originales. Omítelo para usar el comportamiento predeterminado de la API.

Para artículos científicos, consulta Herramientas de investigación: buscan en resúmenes de artículos y texto completo, mientras que categories: ["research"] aquí filtra resultados web ordinarios a sitios web afiliados a la investigación.

Devuelve:

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

Ejemplo de prompt:

"Compara las políticas de estipendio para trabajo remoto entre empresas tecnológicas."

3b. Herramienta de comentarios de búsqueda (firecrawl_search_feedback)

Envía comentarios estructurados sobre un resultado anterior de firecrawl_search. El primer comentario por id de búsqueda reembolsa 1 crédito y mejora la calidad de búsqueda de Firecrawl. Idempotente por id de búsqueda.

Llama a esto después de cada búsqueda que realmente uses (o que no haya ayudado). Comentarios malos/parciales con missingContent son tan valiosos como los buenos.

Exclusión voluntaria: establece 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 del equipo también pueden deshabilitar los comentarios en el servidor; en ese caso, la herramienta está registrada 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: se agregan entre equipos y nos dicen 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 comentarios pero ya no reembolsan créditos. La respuesta establece dailyCapReached: true. Los agentes deben dejar de llamar a esta herramienta por el resto del día UTC cuando vean esa marca.

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 comentarios genéricos (firecrawl_feedback)

Envía comentarios estructurados para un trabajo de endpoint v2 completado a través de /v2/feedback. Úsalo para comentarios a nivel de endpoint en trabajos de scrape, parse, map o search. Para la calidad de los resultados de búsqueda específicamente, prefiere firecrawl_search_feedback porque incluye guía específica de búsqueda.

Mantén los comentarios concisos: usa códigos de problema, etiquetas, notas cortas, URLs, números de página y objetos de metadatos pequeños. No incluyas salidas crudas de scrape/parse.

Exclusión voluntaria: establece 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, consulta hasta que alcanza un estado terminal y devuelve el estado/datos finales del rastreo.

Mejor para:

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

No recomendado para:

• Extraer contenido de una sola página (usa scrape)
• Cuando los límites de tokens son una preocupación (usa map + scrape para un control más estricto)
• Cuando necesitas 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. Limita la profundidad del rastreo y el número de páginas, o usa map + scrape para un control más estricto.

Errores comunes:

• Establecer limit o maxDiscoveryDepth demasiado alto (causa desbordamiento de tokens)
• Usar crawl para una sola página (usa scrape en su lugar)

Ejemplo de prompt:

"Obtén todas las publicaciones de blog de los primeros dos 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 de la consulta interna, incluyendo id, status, completed, total, creditsUsed, expiresAt, next y data. Usa el id devuelto con firecrawl_check_crawl_status si necesitas volver a verificar el trabajo más tarde.

5. Verificar estado del rastreo (firecrawl_check_crawl_status)

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

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

Mejor 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 de dos pasos; las lecturas directas de archivos locales requieren un FIRECRAWL_API_URL autoalojado.

No recomendado para: URLs remotas (usa scrape), múltiples archivos en una sola llamada (llama a parse una vez por archivo) o acciones solo de navegador como capturas de pantalla y clics.

Flujo MCP alojado: MCP alojado no puede leer el sistema de archivos del llamador directamente. Llama a firecrawl_parse con filePath para recibir un comando de carga de corta duración y nextToolCall, sube el archivo localmente, luego llama 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 local npx firecrawl-mcp, el análisis directo de archivos actualmente requiere FIRECRAWL_API_URL apuntando a una API de Firecrawl autoalojada; un servidor local simple solo con clave de API en la nube no puede leer y subir 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. Datos estructurados con Scrape JSON

Para datos estructurados de una página conocida, llama a firecrawl_scrape una vez por URL con formats: ["json"]. Pon el prompt de extracción y el esquema JSON en jsonOptions.

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

Para URLs desconocidas o investigación de múltiples fuentes, usa firecrawl_search o firecrawl_agent antes de Scrape.

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 por páginas y extrae datos estructurados según tu 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 asincrónicamente: devuelve un ID de trabajo inmediatamente, y consultas firecrawl_agent_status para verificar cuándo está completo y recuperar resultados.

Flujo asincrónico:

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

Mejor para:

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

No recomendado para:

• Extracción simple de una sola página donde conoces la URL (usa scrape con formato JSON: más rápido y barato)

Argumentos:

• prompt: Descripción en lenguaje natural de los datos que deseas (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 a los fundadores de Firecrawl y sus antecedentes"

Ejemplo de uso (iniciar agente, luego consultar 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 consulta 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. Usa firecrawl_agent_status para consultar resultados.

9. Verificar estado del agente (firecrawl_agent_status)

Verifica el estado de un trabajo de agente y recupera resultados cuando esté completo. Úsalo para consultar resultados después de iniciar un agente.

Patrón de consulta: La investigación del agente puede tomar minutos para consultas complejas. Consulta 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 aún está investigando: verifica más tarde
• completed: Investigación terminada: la respuesta incluye los datos extraídos
• failed: Ocurrió un error

10. Herramienta de interacción (firecrawl_interact)

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

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

Opciones de uso:

• Pasa url para extraer y abrir una página para interacción en una sola llamada MCP.
• Pasa scrapeId para continuar interactuando con una página ya extraída.
• Pasa exactamente uno de url o scrapeId, más ya sea 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 de detener interacción (firecrawl_interact_stop)

Detén una sesión de interacción para una página extraída cuando hayas terminado de interactuar.

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

12. Herramientas de investigación (firecrawl_research_*)

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

Cubre: resúmenes de artículos y texto completo en literatura biomédica, de ciencias de la vida y clínica (PubMed, bioRxiv, medRxiv) junto con arXiv y otras fuentes científicas.

Herramientas de investigación disponibles:

• firecrawl_research_search_papers: busca metadatos de artículos y resúmenes con una consulta en lenguaje natural, con filtros opcionales de autor, categoría y fecha.
• firecrawl_research_inspect_paper: recupera metadatos canónicos para un ID de artículo (arXiv, PMC, PMID o DOI).
• firecrawl_research_related_papers: expande desde uno o más artículos ancla a través del grafo de citas.
• firecrawl_research_read_paper: lee pasajes de texto completo de un artículo específico.
• firecrawl_research_search_github: busca contenido indexado de issues públicos de GitHub, pull requests y README.

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

firecrawl_search con categories: ["research"] es una superficie diferente: filtra resultados web ordinarios a sitios web afiliados a la investigación y devuelve fragmentos de página, no registros de artículos. Usa estas herramientas cuando la pregunta sea sobre la literatura en sí, y pasa varias formulaciones distintas de la misma pregunta: muestran artículos diferentes a los de una sola consulta.

13. Herramientas de monitoreo (firecrawl_monitor_*)

Crea y gestiona monitores de página 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.

Mejor para:

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

Patrón de creación recomendado: Usa page o pages más goal. El servidor MCP construye la solicitud de monitorización con una programación de 30 minutos y la API habilita la evaluación automática de cambios significativos.

La evaluación de cambios significativos se ejecuta automáticamente cuando goal está configurado. Los webhooks de página exponen isMeaningful y judgment en eventos monitor.page.

Escribe los objetivos como instrucciones de monitorización concisas de 2 a 3 frases. Indica qué debería disparar una alerta, conserva cualquier alcance que el usuario haya dado e incluye exclusiones específicas de la 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 elementos de página no relacionados, ya lo maneja el evaluador, así que no lo repitas en cada objetivo. Si el usuario es vago, mantén el objetivo amplio; si pide monitorización amplia o "cualquier cambio", consérvalo. Si el usuario dice que no le importa algo, inclúyelo 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:

Pasa body cuando necesites 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 monitorización:

• firecrawl_monitor_list: lista los monitores.
• firecrawl_monitor_get: obtiene un monitor.
• firecrawl_monitor_update: actualiza campos, incluidos goal, judgeEnabled, webhook y notification.
• firecrawl_monitor_run: ejecuta una comprobación ahora.
• firecrawl_monitor_delete: elimina un monitor (destructivo; solo llámalo cuando el usuario tenga la intención de eliminarlo).
• firecrawl_monitor_checks: lista las comprobaciones, opcionalmente filtradas por estado.
• firecrawl_monitor_check: obtiene resultados a nivel de página, incluidos diff, snapshot, judgment.meaningful y judgment.meaningfulChanges.

14. Herramienta de búsqueda para desarrolladores (firecrawl_developer_search)

Busca en un índice creado para agentes de codificación. El índice cubre issues de GitHub, pull requests fusionadas, READMEs de repositorios y sitios de documentación seleccionados.

Ideal para: Una pregunta de programación: comportamiento de código, una librería o framework, un contrato de API, un mensaje de error o un bug conocido.

Argumentos:

{
  "name": "firecrawl_developer_search",
  "arguments": {
    "query": "how do I configure retries",
    "k": 10,
    "skills": "only"
  }
}

• query (obligatorio): la pregunta o frase de búsqueda para desarrolladores.
• k: número de resultados clasificados. El valor predeterminado es 10 y el máximo es 100.
• skills: establécelo en "only" para buscar solo archivos de habilidades de agentes.

Devuelve: Resultados clasificados. Cada resultado incluye un ID, un tipo de fuente (issue, pull_request, readme o doc), una URL, un título y los pasajes coincidentes en markdown.

firecrawl_search con categories: ["developer"] busca en el mismo índice junto a los resultados web. Usa esta herramienta en su lugar cuando quieras los pasajes y no los resultados web. El endpoint solo de búsqueda no expone esta herramienta; mantiene su conjunto fijo de seis herramientas, y firecrawl_search llega al índice de desarrolladores allí.

Sistema de registro

El servidor incluye un registro exhaustivo:

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

Ejemplos 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 robusto de errores:

• Errores de límite de tasa de la API mostrados 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. Haz un fork del repositorio
2. Crea tu rama de funcionalidad
3. Ejecuta las pruebas: npm test
4. Envía un pull request

Agradecimientos a los contribuyentes

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.