Firecrawl MCP

Servidor MCP de Firecrawl

Un servidor de Protocolo de Contexto de Modelo (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.

Un gran agradecimiento a @vrknetha y @knacklabs por la implementación inicial.

Características

• Busca en la web y obtén el contenido completo de las páginas
• Busca en un índice creado para agentes de codificación: issues de GitHub, pull requests fusionadas, READMEs y documentación
• Extrae cualquier URL y conviértela 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 para la nube y autoalojamiento
• Soporte para SSE

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

Cuándo Usar Este Servidor

• Usa firecrawl_scrape cuando tengas una URL conocida y quieras su contenido como markdown o como JSON que coincida con un esquema que proporciones.
• Usa firecrawl_map cuando necesites descubrir URLs en un sitio sin obtener su contenido.
• Usa firecrawl_crawl cuando necesites contenido de muchas páginas dentro de un sitio; establece limit, includePaths/excludePaths o maxDiscoveryDepth para limitarlo.
• Usa firecrawl_search cuando partas de una consulta en lugar de una URL y quieras resultados web clasificados; añade scrapeOptions si también quieres que se obtenga el contenido de la página en la misma llamada (el endpoint solo de búsqueda nunca obtiene contenido).
• Usa firecrawl_interact cuando una página necesite una acción de clic, escritura o navegación antes de poder leerla: pasa un url para una página nueva o un scrapeId para continuar en una que ya hayas extraído.
• Usa las herramientas de firecrawl_monitor_* cuando la misma página deba revisarse en un horario recurrente con diferencias y alertas de cambios, en lugar de obtenerse una sola vez.
• Considera otra opción cuando necesites mantener una sesión de navegador abierta a lo largo de muchos pasos propios con tu propia lógica de reintentos y terminación: cada llamada a firecrawl_interact ejecuta un turno de prompt o code hasta completarse y devuelve el control; la sesión puede persistir entre llamadas mediante scrapeId y termina con firecrawl_interact_stop, pero no puedes manejarla de forma interactiva paso a paso desde el lado del cliente dentro de una sola llamada.

Este servidor lista 25 herramientas cuando el perfil completo se registra con la configuración predeterminada (herramientas de comentarios incluidas, sin ejecutarse en modo local sin clave). Establecer FIRECRAWL_NO_SEARCH_FEEDBACK=1 y/o FIRECRAWL_NO_ENDPOINT_FEEDBACK=1 elimina las herramientas de comentarios correspondientes y reduce este número, al igual que el inicio local sin clave. Para clientes con un límite de espacios para herramientas: el endpoint alojado sin clave (https://mcp.firecrawl.dev/v2/mcp, sin clave de API) expone solo 3 — firecrawl_scrape, firecrawl_search, firecrawl_parse — y el endpoint dedicado solo de búsqueda (https://mcp.firecrawl.dev/v2/mcp-search) expone un conjunto fijo de 6 herramientas de solo lectura.

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 una 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 no supervisada), 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 administrador 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 solo de búsqueda

Una superficie de solo lectura y solo búsqueda también está alojada en:

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

Expone un conjunto fijo de seis herramientas de solo lectura: firecrawl_search, firecrawl_developer_search y las cuatro herramientas de firecrawl_research_*. No realiza obtención de contenido de páginas y tiene su propia identidad OAuth; el endpoint completo anterior no cambia. 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 la versión 0.45.6+ de Cursor Para las instrucciones de configuración más actualizadas, consulta la documentación oficial de Cursor sobre cómo configurar servidores MCP: Guía de configuración de servidores 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 el nombre que prefieras)
   • Tipo: "comando"
   • 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 desde https://www.firecrawl.dev/app/api-keys

Después de agregarlo, actualiza la lista de servidores MCP para ver las nuevas herramientas. El Agente Composer usará automáticamente Firecrawl MCP cuando sea apropiado, pero puedes solicitarlo explícitamente describiendo tus necesidades de extracción web. Accede al Composer 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 de 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 mediante Smithery (Legado)

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

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

Ejecutar 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 Configuración de Usuario (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 al usar la API en la nube (predeterminada)
  • Opcional al usar 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)

OAuth de MCP (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 de portador 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 solo de búsqueda (alojada)

En modo alojado (CLOUD_SERVICE=true), una segunda instancia en el mismo proceso sirve el endpoint solo de 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 por OAuth es https://mcp.firecrawl.dev/v2/mcp-search.

FIRECRAWL_MCP_SEARCH_ENABLED (predeterminado true) es el interruptor operativo compatible; establécelo 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 de 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 el uso de la API en la nube:

export FIRECRAWL_API_KEY=your-api-key

Para una 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 URLs conocidas: llama a scrape para cada URL. Si necesitas específicamente una operación de API masiva, usa el endpoint de lote de la API de Firecrawl fuera de MCP.
• Si necesitas descubrir URLs 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 en 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 de múltiples fuentes que devuelva datos estructurados, no conoces las URLs o la respuesta abarca varios sitios (una entidad más sus campos, una lista, un conjunto de datos): usa agent
• Si quieres analizar un sitio completo o una sección: usa crawl (¡con límites!)
• Si necesitas automatización interactiva del navegador (clic, escritura, navegación): 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 más estricto de la extracción

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 URLs 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 de múltiples fuentes, sitios desconocidos o muchos	JSON (datos estructurados)
monitor	Verificaciones recurrentes de páginas	metadatos de monitor/verificación y diferencias
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 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 del 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 de Scraping (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 de scraping repetidas para URLs conocidas, o map + scrape para descubrir URLs primero, o crawl para contenido completo de páginas)
• Cuando no estás seguro de qué página contiene la información (usa búsqueda)

Errores comunes:

• Pasar una lista de URLs a una sola llamada de scraping. Llama al scraping una vez por URL en MCP. Si necesitas específicamente una operación de API masiva, usa el endpoint de lote 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 del contexto.
• Formato Markdown: Solo cuando la tarea realmente requiere 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 contenido completo):

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

Ejemplo de Uso (formato de marca - extrae identidad de marca):

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

Formato de marca: Extrae 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: Establece 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 de Mapa (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 scraping)
• Cuando necesitas el contenido de las páginas (usa scraping 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.

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 scraping)
• Cuando necesitas cobertura completa de un solo sitio web (usa map o crawl)

Errores comunes:

• Usar crawl o map para preguntas abiertas (usa búsqueda 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 fragmentos 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 haber usado 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 de 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 comentarios 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 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 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 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 scraping/parseo.

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 Crawl (firecrawl_crawl)

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

Ideal para:

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

No recomendado para:

• Extraer contenido de una sola página (usa scraping)
• 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 crawl puede ser lento)

Advertencia: Las respuestas de crawl pueden ser muy grandes y pueden exceder los límites de tokens. Limita la profundidad del crawl 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 scraping 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 crawl 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 Crawl (firecrawl_check_crawl_status)

Verifica el estado y los resultados de un trabajo de crawl existente por ID.

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

Devuelve:

• La respuesta incluye el estado del trabajo de crawl:

6. Herramienta de Parseo (firecrawl_parse)

Parsea 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 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 scraping), múltiples archivos en una sola llamada (llama al parseo 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 npx firecrawl-mcp local, el parseo 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 parseado 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"]
      }
    }
  }
}

Cuando las URLs no son conocidas o los datos abarcan varios sitios, usa firecrawl_agent para investigación de múltiples fuentes.

8. Herramienta de Agente (firecrawl_agent)

Agente de investigación web autónomo que devuelve datos estructurados cuando no conoces las URLs o la respuesta abarca varios sitios. Describe los campos que necesitas, opcionalmente pasa un esquema JSON y URLs semilla, y el agente busca, navega, lee páginas y devuelve JSON ensamblado de múltiples fuentes. Úsalo para una entidad más sus campos, para listas y conjuntos de datos, y para páginas que necesitan navegación para llegar a los datos. Para una URL conocida, usa firecrawl_scrape con formato JSON en su lugar.

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

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

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

Argumentos:

• prompt: Descripción en lenguaje natural de los datos que deseas (requerido, 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 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: La investigación terminó: 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. Ideal para: Hacer clic, escribir, navegar y extraer el 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 interactuar en una sola llamada MCP.
• Pase scrapeId para continuar interactuando con una página ya extraída.
• 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: El resultado de la interacción y, en modo URL, el scrapeId derivado para seguimiento o limpieza.

11. Herramienta 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.

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: busque 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: recupere metadatos canónicos para un ID de artículo (arXiv, PMC, PMID o DOI).
• firecrawl_research_related_papers: expanda desde uno o más artículos ancla a través del grafo de citas.
• firecrawl_research_read_paper: lea pasajes de texto completo de un artículo específico.

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 un raspado 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. Use estas herramientas cuando la pregunta sea sobre la literatura en sí, y pase varias formulaciones distintas de la misma pregunta: muestran artículos diferentes a los de una sola consulta.

13. Herramientas de Monitoreo (firecrawl_monitor_*)

Cree y gestione monitores de página recurrentes. Los monitores ejecutan raspados 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 inglés 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 monitoreo con un horario de 30 minutos y la API habilita la evaluación de cambios significativos automáticamente.

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.

Escriba los objetivos como instrucciones de monitoreo concisas de 2 a 3 oraciones. Diga qué debería activar una alerta, preserve cualquier alcance que el usuario haya dado e incluya exclusiones específicas de la intención solo cuando sea obvio 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 es manejado por el evaluador, así que no lo repita en cada objetivo. Si el usuario es vago, mantenga el objetivo amplio; si pide monitoreo amplio o "cualquier cambio", preserve eso. 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 monitoreo:

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

14. Herramienta de Búsqueda para Desarrolladores (firecrawl_developer_search)

Busque en un índice construido para agentes de codificación. El índice cubre problemas de GitHub, solicitudes de extracción fusionadas, READMEs de repositorios y sitios de documentación seleccionados.

Ideal para: Una pregunta de programación: comportamiento de código, una biblioteca o marco de trabajo, un contrato de API, un mensaje de error o un error 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 del desarrollador.
• k: número de resultados clasificados. El valor predeterminado es 10 y el máximo es 100.
• skills: configúrelo en "only" para buscar solo archivos de habilidades de agente.

Devuelve: Resultados clasificados. Cada resultado lleva 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 el mismo índice junto a los resultados web. Use esta herramienta en su lugar cuando quiera los pasajes coincidentes, el filtro skills o ningún resultado web en la respuesta. El endpoint solo de búsqueda expone ambas herramientas, y la misma elección aplica allí.

Sistema de Registro

El servidor incluye registro integral:

• Estado y progreso de operaciones
• Métricas de rendimiento
• Seguimiento de límites de velocidad
• 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 velocidad de 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. Haga un fork del repositorio
2. Cree su rama de características
3. Ejecute las pruebas: npm test
4. Envíe una solicitud de extracción

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: consulte el archivo LICENSE para obtener detalles