Firecrawl MCP

Servidor MCP de Firecrawl

Un servidor de Model Context Protocol (MCP) que lleva Firecrawl, la API de contexto para agentes de IA, a clientes compatibles con MCP: busca, extrae y interactúa con la web en vivo y obtén Markdown limpio o datos estructurados.

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

Características

• Busca en la web, opcionalmente con el contenido completo de la página para cada resultado
• Busca en índices de fuentes para desarrolladores (issues de GitHub, pull requests fusionados, READMEs y documentación), fuentes del gobierno de EE. UU. y artículos científicos (PubMed, bioRxiv, medRxiv, arXiv)
• Extrae cualquier URL en Markdown limpio o JSON estructurado
• Analiza PDFs y documentos
• Rastrea un sitio para obtener contenido de muchas páginas, o mapéalo para descubrir sus URLs
• Interactúa con páginas en un navegador real: haz clic, escribe, rellena formularios y navega por páginas dinámicas
• Ejecuta trabajos de Agent para investigación de múltiples fuentes que devuelve datos estructurados
• Monitorea páginas y recibe notificaciones cuando su contenido cambie
• Consulta el uso actual e histórico de créditos de Firecrawl
• Reintentos automáticos y limitación de velocidad
• Soporte para la nube y autoalojado
• Soporte de 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 de un sitio; establece limit, includePaths/excludePaths o maxDiscoveryDepth para acotarlo.
• Usa firecrawl_search cuando partas de una consulta en lugar de una URL y quieras resultados web clasificados. Los resultados incluyen extractos; obtén las páginas completas con firecrawl_scrape en las URLs que necesites. scrapeOptions obtiene la página de cada resultado en la misma llamada y factura cada una como un scrape, así que resérvalo para el texto completo de unos pocos resultados (el endpoint de solo búsqueda nunca obtiene contenido).
• Usa firecrawl_interact cuando una página necesite una acción de clic, escritura o navegación antes de que puedas leerla: pasa un url para una página nueva o un scrapeId para continuar en una que ya extrajiste.
• Usa las herramientas 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.
• Usa firecrawl_credit_usage para consultar los créditos restantes o en qué se gastaron los créditos, por mes o por día, opcionalmente desglosados por endpoint o clave de API.
• Considera otra opción cuando necesites mantener una sesión de navegador abierta a lo largo de muchos de tus propios pasos con tu propia lógica de reintentos y terminación: cada llamada a firecrawl_interact ejecuta un turno de prompt o code hasta completarlo y devuelve el control. La sesión puede persistir entre llamadas mediante scrapeId y termina con firecrawl_interact_stop, pero no puedes controlarla interactivamente paso a paso desde el lado del cliente dentro de una sola llamada.

Este servidor lista 27 herramientas cuando el perfil completo se registra con la configuración predeterminada (incluidas las herramientas de feedback, sin ejecutarse en modo local sin clave). Establecer FIRECRAWL_NO_SEARCH_FEEDBACK=1 y/o FIRECRAWL_NO_ENDPOINT_FEEDBACK=1 elimina las herramientas de feedback correspondientes y reduce este conteo, al igual que el inicio local sin clave. Para clientes con un límite de espacios de 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 de solo búsqueda (https://mcp.firecrawl.dev/v2/mcp-search) expone un conjunto fijo de 9 herramientas (búsqueda para desarrolladores, gobierno e investigación, más la consulta y ejecución del catálogo de Alexandria).

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 interactiva de cuenta, configura tu cliente MCP para usar esta URL de servidor. Este es un endpoint MCP, no una página de navegador; usa el flujo de conexión de cuenta del cliente y no añadas 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 la opción 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 del MCP alojado y la guía de incorporación de agentes para instrucciones específicas de cada cliente.

Nombrar tu integración

Una integración que se conecta por HTTP puede nombrarse a sí misma con un encabezado X-Firecrawl-Origin, por ejemplo X-Firecrawl-Origin: my-agent. El servidor lo reporta a Firecrawl como el origen de la solicitud mcp-my-agent@<server version>, en lugar del nombre del cliente o el User-Agent que reportaría de otro modo. Usa letras, dígitos y guiones: cada secuencia de otros caracteres se convierte en un guion, los guiones iniciales y finales se eliminan, y el nombre se corta a 48 caracteres. Los resultados de las herramientas no se ven afectados; solo cambia el origen enviado a la API de Firecrawl (y pasado al beforeKeylessRequest de un embedder).

Endpoint de solo búsqueda

También se aloja una superficie de búsqueda de alcance fijo en:

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

Expone un conjunto fijo de nueve herramientas: firecrawl_search, firecrawl_developer_search, firecrawl_gov_search, las cuatro herramientas firecrawl_research_* y las dos herramientas de Alexandria firecrawl_find_tools y firecrawl_scrape. Su firecrawl_search no obtiene contenido de páginas.

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

Configurar 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 Features > MCP Servers
3. Haz clic en "+ Add new global MCP server"
4. Introduce 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. Introduce lo siguiente:
   • Nombre: "firecrawl-mcp" (o tu nombre preferido)
   • 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 añadir, 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 lo que necesitas de la web. Accede al Composer con Command+L (Mac), selecciona "Agent" junto al botón de envío e introduce tu consulta.

Ejecutar en Windsurf

Añade 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 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

En este modo, el servidor solo responde a solicitudes dirigidas a localhost, 127.0.0.1 o [::1] (en cualquier puerto), además de la dirección en HOST cuando no es 0.0.0.0 ni ::. Una solicitud cuyo encabezado Host nombre otro host, o cuyo encabezado Origin nombre otro sitio, recibe 403, y los encabezados CORS reflejan un origen permitido en lugar de *. Las solicitudes GET y HEAD a /health se responden independientemente del host, para que las comprobaciones de estado sigan funcionando, y el servidor registra una línea nombrando FIRECRAWL_MCP_ALLOWED_HOSTS por cada solicitud que rechaza. Esto evita que las páginas web que visitas llamen al servidor local mediante DNS rebinding o solicitudes de origen cruzado y usen su FIRECRAWL_API_KEY.

Para acceder al servidor bajo otro nombre o dirección, como un nombre de host detrás de un proxy inverso o una IP de LAN, lístalo en FIRECRAWL_MCP_ALLOWED_HOSTS (separado por comas; los puertos se ignoran). La misma lista decide qué orígenes de navegador pueden llamar al servidor. Un proxy inverso en la misma máquina puede mantener la dirección de enlace predeterminada:

env HTTP_STREAMABLE_SERVER=true FIRECRAWL_API_KEY=fc-YOUR_API_KEY \
  FIRECRAWL_MCP_ALLOWED_HOSTS=mcp.home.lan npx -y firecrawl-mcp

Los clientes en otras máquinas también necesitan que el servidor escuche en una dirección no loopback, así que establece HOST también. Entonces cada cliente que pueda alcanzar el puerto será servido con el FIRECRAWL_API_KEY del servidor, así que haz esto solo en una red de confianza:

env HTTP_STREAMABLE_SERVER=true FIRECRAWL_API_KEY=fc-YOUR_API_KEY HOST=0.0.0.0 \
  FIRECRAWL_MCP_ALLOWED_HOSTS=192.168.1.20 npx -y firecrawl-mcp

FIRECRAWL_MCP_ALLOWED_HOSTS=* desactiva la comprobación y restaura el encabezado CORS comodín. Hazlo solo cuando algo delante del servidor compruebe hosts y orígenes por sí mismo.

Ejecutar con Docker

La imagen ghcr.io/firecrawl/firecrawl-mcp-server ejecuta el mismo servidor que npx -y firecrawl-mcp. Cada compilación desde main se etiqueta como latest, v<package version> y sha-<commit sha>. v<package version> pasa a la compilación más reciente de esa versión, así que fija sha-<commit sha> (o un digest) cuando necesites una imagen fija.

stdio (el predeterminado), para clientes MCP que lanzan el servidor como un comando:

docker run -i --rm -e FIRECRAWL_API_KEY=fc-YOUR_API_KEY ghcr.io/firecrawl/firecrawl-mcp-server:latest

{
  "mcpServers": {
    "firecrawl-mcp": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "FIRECRAWL_API_KEY", "ghcr.io/firecrawl/firecrawl-mcp-server:latest"],
      "env": {
        "FIRECRAWL_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Streamable HTTP, servido en http://localhost:3000/mcp:

docker run --rm -p 127.0.0.1:3000:3000 \
  -e HTTP_STREAMABLE_SERVER=true \
  -e FIRECRAWL_API_KEY=fc-YOUR_API_KEY \
  ghcr.io/firecrawl/firecrawl-mcp-server:latest

La imagen establece HOST=0.0.0.0 y PORT=3000; sobrescribe PORT (y la asignación de -p) para escuchar en otro lugar. El servidor usa el FIRECRAWL_API_KEY del contenedor para solicitudes que no envían su propia credencial, así que el ejemplo publica el puerto solo en 127.0.0.1; no lo expongas más ampliamente a menos que los clientes deban proporcionar su propia clave. Establece FIRECRAWL_API_URL para usar una API de Firecrawl autoalojada. El contenedor se ejecuta como el usuario sin privilegios node. El servidor solo responde a localhost, 127.0.0.1 y [::1] en los encabezados Host y Origin, así que la asignación de -p 127.0.0.1:3000:3000 funciona tal cual; para acceder a él bajo otro nombre, establece -e FIRECRAWL_MCP_ALLOWED_HOSTS=<host> (consulta Modo local de Streamable HTTP).

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, añade el siguiente bloque JSON a tu archivo User Settings (JSON) en VS Code. Puedes hacerlo pulsando 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 añadirlo 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 (predeterminado)
  • 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)
• FIRECRAWL_INTEGRATION (Opcional): Etiqueta de integración para aplicaciones que lanzan este servidor, como una extensión de editor
  • Se envía como el campo integration de las solicitudes de scrape, batch scrape, crawl, map, search, extract, agent, parse, interact y feedback
  • Usa un valor que empiece por _, por ejemplo _zed

Modo HTTP local

• FIRECRAWL_MCP_ALLOWED_HOSTS (Opcional): Nombres de host o direcciones adicionales con los que el servidor responde mediante HTTP_STREAMABLE_SERVER=true o SSE_LOCAL=true, separados por comas
  • localhost, 127.0.0.1, [::1] y un HOST sin comodines siempre están permitidos; los puertos se ignoran
  • Las solicitudes cuyo encabezado Host o Origin nombre cualquier otro host reciben 403, excepto las solicitudes GET y HEAD a /health
  • * desactiva la comprobación; no se usa con CLOUD_SERVICE=true, que responde a cualquier host

MCP OAuth (tokens de acceso Bearer)

Firecrawl emite 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 de 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 scrape/search.

CLOUD_SERVICE=true

CLOUD_SERVICE=true sirve las herramientas mediante HTTP transmitible en PORT (por defecto 3000, vinculado a 0.0.0.0) con valores predeterminados más estrictos: cada solicitud debe llevar una credencial (una clave de API o un token de acceso OAuth), scrape es de solo lectura (consulta la herramienta scrape a continuación) y firecrawl_parse solo acepta cargas.

FASTMCP_ENDPOINT selecciona la superficie de herramientas: /v2/mcp (predeterminado) para el conjunto completo de herramientas, /v2/mcp-oauth para la superficie de cuenta, o /v2/mcp-search para las herramientas de solo búsqueda (esto también requiere FIRECRAWL_MCP_SEARCH_OAUTH_ONLY=true). Con la superficie completa, una instancia de solo búsqueda también se inicia en el puerto 3001; establece FIRECRAWL_MCP_SEARCH_ENABLED=false para desactivarla.

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

Añade 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 específicamente necesitas una única operación de API masiva, usa el endpoint por lotes 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 bug conocido): usa developer search
• Si tienes una pregunta legal o regulatoria (un estatuto, reglamento, código, opinión judicial u otra publicación del gobierno de EE. UU.): usa el Firecrawl Government Index
• Si necesitas artículos científicos (literatura biomédica, de ciencias de la vida, clínica o de arXiv): usa las herramientas de investigación, que buscan en resúmenes y texto completo de artículos. search con categories: ["research"] es algo distinto: un filtro de sitios web sobre resultados web ordinarios.
• Si necesitas investigación de múltiples fuentes que devuelva datos estructurados, no conoces las URL o la respuesta abarca varios sitios (una entidad y 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 (hacer clic, escribir, navegar): usa interact con una URL para una página nueva, o scrape + interact cuando ya hayas scrapeado la página o necesites un control más preciso del scrape
• Si necesitas datos de un proveedor catalogado (Alexandria): busca con sources: ["alexandria"], inspecciona el contrato seleccionado con find_tools y ejecútalo con scrape alexandria

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 una página scrapeada	Resultado de ejecución + scrapeId para el modo URL
map	Descubrir URL en un sitio	URL[]
crawl	Extracción de varias páginas (con límites)	estado/datos finales del crawl tras el sondeo interno
parse	Archivos y referencias de cargas alojadas	markdown, JSON o salida de documento
search	Búsqueda web de información	results[]
find_tools	Navegación del catálogo de Alexandria y búsqueda de URL	proveedores, contratos de herramientas y navegación nextTool
developer	Preguntas de programación sobre fuentes para desarrolladores	results[] con pasajes
gov	Derecho primario y material regulatorio de EE. UU.	results[] con fragmentos
agent	Investigación de múltiples fuentes, sitios desconocidos o numerosos	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 repos

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 basado en lo que necesitas 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 entero para resumirlo o analizar la estructura de la página.

Herramientas disponibles

1. Herramienta Scrape (firecrawl_scrape)

Extrae contenido de una única 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 varias páginas (usa llamadas repetidas a scrape para URL conocidas, o map + scrape para descubrir URL primero, o crawl para el contenido completo de las páginas)
• 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 a scrape. Llama a scrape una vez por URL en MCP. Si específicamente necesitas una única operación de API masiva, usa el endpoint por lotes 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 (p. ej., resumir un artículo entero, 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 branding - extraer la identidad de marca):

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

Formato branding: Extrae una 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 la información de identificación personal redactada. Con CLOUD_SERVICE=true: scrape es de solo lectura. No toma un actions de navegador y no puede aceptar términos de proveedores. Un profile con nombre carga el estado guardado del navegador sin guardar cambios en él, y el firecrawl_search del endpoint completo trata scrapeOptions.profile de la misma manera. Para guardar el estado del navegador en un perfil, abre la página con firecrawl_interact (ver abajo). Un administrador de la organización acepta los términos en el panel de control.

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.

Ideal para:

• Descubrir URL en un sitio web antes de decidir qué scrapear
• 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 URL en lugar de map

Ejemplo de prompt:

"Enumera todas las URL de example.com."

Ejemplo de uso:

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

Devuelve:

• Array de URL 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 varios 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 scrapear (usa scrape)
• Cuando necesitas una cobertura completa de un único 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"
  }
}

Para obtener el texto completo de algunos resultados en la misma llamada, añade "scrapeOptions": { "formats": ["markdown"], "onlyMainContent": true }. Cada resultado obtenido se factura como un scrape, así que para la mayoría de las preguntas usa los extractos y firecrawl_scrape solo las URL que necesites.

Establece highlights en true para solicitar fragmentos destacados relevantes para la consulta, o en false para conservar los fragmentos de búsqueda originales. Omítelo para usar el comportamiento predeterminado de la API.

Añade "sources": ["alexandria"] para el descubrimiento semántico de herramientas en data.tools, opcionalmente combinado con web/news/images. Se requiere una consulta. Usa firecrawl_find_tools para la búsqueda contextual y la divulgación progresiva; consulta Alexandria Tools.

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

Devuelve:

• Resultados de búsqueda agrupados por fuente (data.web, data.images, data.news), con contenido scrapeado opcional, más un campo id. Cada resultado lleva un source y un position indexado desde 1, numerado desde 1 dentro de su propio grupo — copia el par directamente en el valuableResults de firecrawl_search_feedback en lugar de contar elementos del array. 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 subsidio 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). Los comentarios malos/parciales con missingContent son igual de valiosos que los buenos.

Exclusión: 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 podrán llamarla. Los administradores del equipo también pueden desactivar los comentarios del lado del servidor; en ese caso, la herramienta se registra pero siempre devuelve feedbackErrorCode: "TEAM_OPTED_OUT". Campo más importante: missingContent. Es un arreglo de piezas específicas de contenido que el agente esperaba encontrar pero no encontró. Una entrada por cada tema faltante; estas se agregan entre equipos y nos indican qué indexar a continuación. Para obtener resultados útiles, use valuableResults con el par source/position estampado en cada resultado — los resultados se agrupan y cada grupo se numera desde 1 de forma independiente, por lo que ambos son necesarios. Enumere cada resultado útil (los resultados no listados se tratan como no útiles), y reserve valuableSources para URLs útiles que no estuvieran entre los resultados devueltos.

Límite diario de reembolsos (por equipo, por día UTC, 100 créditos por defecto). Una vez que el creditsRefundedToday de un equipo alcanza dailyRefundCap, los envíos posteriores siguen registrando comentarios 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 marca.

Ejemplo de uso:

{
  "name": "firecrawl_search_feedback",
  "arguments": {
    "searchId": "0193f6c5-1234-7890-abcd-1234567890ab",
    "rating": "good",
    "valuableResults": [
      { "source": "web", "position": 1 },
      { "source": "web", "position": 3 },
      { "source": "news", "position": 2, "reason": "Broke the pricing change." }
    ],
    "valuableSources": [
      {
        "url": "https://docs.firecrawl.dev/pricing",
        "reason": "Not in the results; found via a result's pricing link. Answered the question."
      }
    ],
    "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 de { success, feedbackId, creditsRefunded, alreadySubmitted? }.

3c. Herramienta de comentarios genérica (firecrawl_feedback)

Envía comentarios estructurados para un trabajo completado de un endpoint v2 a través de /v2/feedback. Use esto para comentarios a nivel de endpoint sobre 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 para búsquedas.

Mantenga los comentarios concisos: use códigos de problema, etiquetas, notas breves, URLs, números de página y objetos de metadatos pequeños. No incluya salidas sin procesar de scraping/parseo.

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 podrán 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 de { success, feedbackId, creditsRefunded, creditsRefundedToday?, dailyRefundCap?, dailyCapReached?, websiteCapReached?, alreadySubmitted?, warning? }.

4. Herramienta de rastreo (firecrawl_crawl)

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

Ideal para:

• Extraer contenido de varias páginas relacionadas, cuando necesita una cobertura completa.

No recomendado para:

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

Advertencia: Las respuestas de rastreo pueden ser muy grandes y pueden superar los límites de tokens. Limite la profundidad del rastreo y el número de páginas, o use map + scrape para un control más ajustado.

Errores comunes:

• Establecer limit o maxDiscoveryDepth demasiado altos (provoca desbordamiento de tokens)
• Usar crawl para una sola página (use scrape en su lugar)

Ejemplo de prompt:

"Obtén todas las entradas de 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 tras la consulta interna, incluidos id, status, completed, total, creditsUsed, expiresAt, next y data. Use el id devuelto con firecrawl_check_crawl_status si necesita volver a consultar el trabajo más tarde.

5. Consultar estado del rastreo (firecrawl_check_crawl_status)

Consulta 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 parseo (firecrawl_parse)

Parsee 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. El endpoint alojado usa un flujo de carga en dos pasos; las lecturas directas de archivos locales requieren un FIRECRAWL_API_URL autoalojado.

No recomendado para: URLs remotas (use scrape), varios archivos en una sola llamada (llame a parse una vez por archivo), o acciones exclusivas del navegador como capturas de pantalla y clics.

Endpoint alojado: no puede leer su sistema de archivos. Llame a firecrawl_parse con filePath para recibir un comando de carga de corta duración y nextToolCall, cargue el archivo localmente y luego llame a firecrawl_parse de nuevo con el uploadRef devuelto. El paso de carga requiere autenticación de Firecrawl o el nivel sin clave. En modo local de npx firecrawl-mcp, el parseo directo de archivos actualmente requiere FIRECRAWL_API_URL apuntando a una API de Firecrawl autoalojada; un servidor local simple con solo una clave de 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: El contenido del documento parseado o instrucciones de carga alojada con un nextToolCall.

7. Datos estructurados con Scrape JSON

Para obtener datos estructurados de una página conocida, llame a firecrawl_scrape una vez por URL con formats: ["json"]. Coloque 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 se conocen o los datos abarcan varios sitios, use firecrawl_agent para investigación de múltiples fuentes.

8. Herramienta de agente (firecrawl_agent)

Agente autónomo de investigación web que devuelve datos estructurados cuando no conoce las URLs o la respuesta abarca varios sitios. Describa los campos que necesita, opcionalmente pase un esquema JSON y URLs semilla, y el agente busca, navega, lee páginas y devuelve JSON ensamblado a partir de varias fuentes. Úselo para una entidad más sus campos, para listas y conjuntos de datos, y para páginas que requieren navegación para llegar a los datos. Para una URL conocida, use 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 de forma asíncrona — devuelve un ID de trabajo inmediatamente, y usted consulta firecrawl_agent_status para verificar cuándo está completo y recuperar los resultados.

Flujo de trabajo asíncrono:

1. Llame a firecrawl_agent con su prompt/esquema → devuelve el ID del trabajo
2. Haga otro trabajo mientras el agente investiga (puede tardar minutos para consultas complejas)
3. Consulte firecrawl_agent_status con el ID del 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 conoce las URLs exactas
• Recopilación de datos de múltiples fuentes
• Encontrar información dispersa por la web
• Tareas donde puede hacer otro trabajo mientras espera los resultados

No recomendado para:

• Scraping simple de una sola página donde conoce la URL (use scrape con formato JSON — más rápido y económico)

Argumentos:

• prompt: Descripción en lenguaje natural de los datos que desea (obligatorio, máx. 10,000 caracteres)
• urls: Arreglo opcional de URLs para enfocar al agente en páginas específicas
• schema: Esquema JSON opcional para salida estructurada
• effort: Opcional. Presupuesto de razonamiento "low", "medium" o "high" para la tarea del agente.
• maxCredits: Entero positivo opcional. Límite de gasto en créditos para esta ejecución. La API usa 2,500 por defecto cuando se omite, y limita una solicitud gratuita a 2,500.
• strictConstrainToURLs: Booleano opcional. Si es true, el agente solo visita las URLs en urls.
• threadId: Opcional. Continúe un hilo existente: el threadId de un resultado anterior de firecrawl_agent o firecrawl_agent_status. Omítalo para iniciar un nuevo hilo. En un seguimiento, los ajustes omitidos de mode, urls, schema y exchange se heredan del turno anterior.
• mode: Opcional. "extract" (por defecto) devuelve el resultado estructurado completo en cada turno. "chat" permite que un seguimiento que no solicita nuevos datos obtenga una respuesta breve en message en lugar de una nueva ejecución; exchange.requireApproval lo requiere.
• exchange: Opcional. Ajustes del proveedor Alexandria para este turno, reenviados tal cual a POST /v2/agent:
  • enabled, toolkits (hasta 5 slugs de proveedor), maxCalls (1 a 30), requireApproval (las llamadas de pago terminan el turno con un pendingApproval; requiere mode: "chat" en la misma llamada, incluso en un seguimiento)
  • onTermsRequired: qué hacer cuando un proveedor de Alexandria que el agente usaría requiere términos de datos que su equipo no ha aceptado. Nunca se llama a los proveedores restringidos en ningún modo. Omitirlo en un seguimiento conserva el valor del turno anterior.
    • "skip" (por defecto): responder solo con proveedores aceptados. exchange.skippedProviders en el resultado de estado enumera los proveedores restringidos que habrían ayudado.
    • "ask": lo mismo, más un pendingApproval de términos y exchange.requiresAction con el ID de aprobación y los requisitos del proveedor. Lea los términos con terms/show; un administrador de la organización los acepta en el panel de Firecrawl.
  • approve: { approvalId, callIds?, always? } responde sí al pendingApproval en el que terminó el turno anterior. callIds y always se aplican solo a aprobaciones de llamadas de pago.
  • decline: { approvalId } responde no. Una oferta de términos rechazada mantiene a esos proveedores fuera del resto del hilo.
  • approve y decline requieren threadId, y solo se puede enviar uno de ellos.

Términos del proveedor (modo de consulta): no existe un modo de aceptación automática. Cuando un turno termina en una oferta de términos, el resultado de estado lleva pendingApproval (kind: "terms") y exchange.requiresAction con el approvalId y los requisitos del proveedor. Cualquier descriptor terms/accept en esa carga de API no está disponible a través de MCP. Para usar el proveedor:

1. Muestre al usuario los términos (terms/show hasta firecrawl_scrape con alexandria).
2. Indique a un administrador de la organización que acepte los términos en la URL del proveedor, o en configuración de fuentes de datos. Una solicitud de datos no es consentimiento.
3. Espere a que el administrador confirme la aceptación en el panel.
4. Continúe el mismo hilo: llame a firecrawl_agent con el mismo threadId y exchange.approve: { "approvalId": "..." }. Esto reanuda la investigación y no acepta los términos.

Si el usuario dice que no, llame a firecrawl_agent con el mismo threadId y exchange.decline: { "approvalId": "..." } en su lugar.

Ejemplo de prompt:

"Encuentra a los fundadores de Firecrawl y sus trayectorias"

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

Ejemplo de uso (seguimiento en el mismo hilo):

{
  "name": "firecrawl_agent",
  "arguments": {
    "prompt": "Only keep the startups based in Europe",
    "threadId": "0199a1b2-0000-7000-8000-000000000031"
  }
}

Ejemplo de uso (continuar el hilo después de que un administrador confirmó la aceptación en el panel):

{
  "name": "firecrawl_agent",
  "arguments": {
    "prompt": "The admin confirmed acceptance of the Apollo terms in the dashboard. Continue.",
    "threadId": "0199a1b2-0000-7000-8000-000000000031",
    "exchange": { "approve": { "approvalId": "0199a1b2-0000-7000-8000-000000000033" } }
  }
}

Devuelve:

• ID de trabajo para consultar el estado, más threadId y threadTurn. Use firecrawl_agent_status para consultar los resultados.

9. Consultar estado del agente (firecrawl_agent_status)

Consulta el estado de un trabajo de agente y recupera los resultados cuando está completo. Use esto para consultar los resultados después de iniciar un agente.

Patrón de consulta: La investigación del agente puede tardar minutos para consultas complejas. Consulte este endpoint periódicamente (p. ej., 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 sigue investigando — vuelva a consultar 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ú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 el estado de páginas dinámicas sin restaurar las herramientas de navegador obsoletas.

Opciones de uso:

• Pase url para hacer scraping y abrir una página para interacción en una sola llamada MCP.
• Pase scrapeId para continuar interactuando con una página ya scrapeada.
• Para guardar el estado del navegador (cookies, localStorage) en un perfil con nombre, pase url con scrapeOptions: { "profile": { "name": "my-profile", "saveChanges": true } }. El estado se guarda cuando firecrawl_interact_stop termina la sesión.
• 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, para el modo URL, el scrapeId derivado para seguimiento o limpieza.

11. Herramienta de detención de interacción (firecrawl_interact_stop)

Detiene una sesión de interacción para una página scrapeada cuando haya 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 mediante las herramientas de investigación del MCP.

Cubre: resúmenes y texto completo de artículos de 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 y resúmenes de artículos con una consulta en lenguaje natural, con filtros opcionales de autor, categoría y fecha.
• firecrawl_research_inspect_paper: recupera los metadatos canónicos de un ID de artículo (arXiv, PMC, PMID o DOI).
• firecrawl_research_related_papers: amplía desde uno o varios 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.

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

firecrawl_search con categories: ["research"] es una superficie distinta: filtra resultados web ordinarios a sitios web afiliados a la investigación y devuelve fragmentos de páginas, 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, ya que revelan artículos diferentes de los que muestra una sola consulta.

13. Herramientas de monitores (firecrawl_monitor_*)

Crea y gestiona monitores de páginas recurrentes. Los monitores ejecutan scrapes o crawls programados, comparan cada resultado con la última instantánea retenida y pueden notificar por webhook o correo electrónico.

Ideal para:

• Vigilar una página o unas pocas páginas a lo largo del tiempo
• Alertar sobre cambios significativos usando un objetivo en lenguaje natural
• Seguir el historial de comprobaciones y los diffs a nivel de página

Patrón de creación recomendado:

Usa page o pages junto con goal. El servidor MCP construye la solicitud del monitor con una programación de 30 minutos y la API habilita automáticamente la evaluación de cambios significativos.

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

Escribe los objetivos como instrucciones de monitor concisas de 2-3 frases. Indica qué debe activar una alerta, conserva cualquier alcance que haya dado el usuario e incluye exclusiones específicas de la intención solo cuando sean evidentes 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 la 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 una monitorización amplia o "cualquier cambio", consérvalo. Si el usuario dice que algo no le importa, inclúyelo explícitamente.

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

Varias 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 crawl, seguimiento de cambios en 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 monitores:

• 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: activa una comprobación ahora.
• firecrawl_monitor_delete: elimina un monitor (destructivo; llama solo 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 programación. El índice cubre issues de GitHub, pull requests fusionadas, READMEs de repositorios y documentación de código.

Ideal para: una pregunta de programación: el comportamiento de un código, una biblioteca 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 del desarrollador.
• 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 en 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 coincidentes, el filtro skills o que no haya resultados web en la respuesta. El endpoint de solo búsqueda expone ambas herramientas, y la misma elección se aplica allí.

14b. Herramienta de búsqueda en el índice gubernamental (firecrawl_gov_search)

Busca material jurídico y regulatorio primario de fuentes gubernamentales federales, estatales y locales de EE. UU.: estatutos, reglamentos, códigos, opiniones judiciales y otras publicaciones gubernamentales.

Ideal para: una pregunta legal o regulatoria que necesite el texto aplicable o una fuente gubernamental oficial.

Argumentos:

{
  "name": "firecrawl_gov_search",
  "arguments": {
    "query": "excessive force claims against police officers",
    "k": 10,
    "courtType": "federal-appellate",
    "cites": "42 U.S.C. § 1983"
  }
}

• query (obligatorio): la pregunta o frase de búsqueda legal o regulatoria.
• k: número de resultados clasificados. El valor predeterminado es 10 y el máximo es 100.
• jurisdiction: conserva solo páginas de una jurisdicción: "us" para federal, o "us-" más un código de estado o territorio de dos letras, como "us-ca" o "us-dc".
• court: conserva solo páginas etiquetadas para un tribunal, por id de tribunal de CourtListener, como "scotus", "ca9" o "nysd".
• courtType: conserva solo páginas de un tipo de tribunal: federal-supreme, federal-appellate, federal-district, federal-bankruptcy, federal-special, military, state-supreme, state-appellate, state-trial, state-special o state-attorney-general.
• cites: conserva solo páginas que citen una ley o caso, como una cita impresa tal como "42 U.S.C. § 1983" o "5 U.S. 137", o un id de cita como "us:usc:42:1983".
• domain: conserva solo páginas de un sitio, como "irs.gov".

Los filtros son opcionales y se combinan: un resultado debe coincidir con todos los filtros establecidos. Los filtros conservan solo las páginas que el índice ha etiquetado, por lo que una búsqueda filtrada puede omitir páginas relevantes, y que no haya resultados no significa que no existan. Las etiquetas de tribunal son más completas para tribunales federales y colecciones de jurisprudencia.

Devuelve: resultados clasificados. Cada resultado incluye una posición, un título, una URL y el fragmento coincidente. El endpoint de solo búsqueda también expone esta herramienta.

firecrawl_search con categories: ["gov"] busca en las mismas fuentes y devuelve los resultados en data.web con category: "gov". La categoría gov no acepta estos filtros y no se puede combinar con otras categorías.

15. Herramientas de Alexandria

Firecrawl Alexandria es un catálogo de proveedores de datos accesibles a través de la API de Firecrawl con una clave de API de Firecrawl en un equipo con acceso a Alexandria. Las sesiones sin clave (alojadas o locales) obtienen Alexandria requires an API key on a team with Alexandria access; las herramientas de descubrimiento de Alexandria no se listan para sesiones alojadas sin clave.

Descubrimiento semántico (firecrawl_search):

{
  "name": "firecrawl_search",
  "arguments": {
    "query": "podcast conversations about AI agents",
    "sources": ["web", "alexandria"],
    "domainTools": true,
    "limit": 2
  }
}

data.tools devuelve por defecto sugerencias compactas con proveedor, capacidad y descripción. Establece toolDetail: "summary" para metadatos y navegación, o toolDetail: "full" para contratos que incluyen entradas, campos de respuesta y ejemplos. domainTools: true añade coincidencias contextuales a las menciones de consulta y las URL de resultados en ese mismo array. Consulta warning para el descubrimiento no disponible. La búsqueda requiere una consulta y no acepta filtros de recorrido del catálogo. Este descubrimiento funciona tanto en las superficies MCP completas como en las de solo búsqueda.

Divulgación progresiva (firecrawl_find_tools):

{
  "name": "firecrawl_find_tools",
  "arguments": {
    "providers": ["particle"],
    "capabilities": ["podcasts/episodes/search"],
    "expand": ["options", "response", "examples"],
    "limit": 2
  }
}

Empieza sin argumentos para ver las categorías y luego acota progresivamente el catálogo:

Argumentos	Resultado
{}	Categorías y descripciones breves
{"categories":["podcasts"]}	Proveedores de esa categoría
{"categories":["podcasts"],"providers":["particle"]}	Nombres y descripciones compactos de herramientas
{"providers":["particle"],"capabilities":["podcasts/episodes/search"]}	Entradas, restricciones, respuesta y ejemplos completos seleccionados

No se requiere ningún salto de grupo. level explícito admite categories, providers, groups o tools; expand explícito selecciona secciones del contrato. expand: [] mantiene los resultados compactos incluso al seleccionar una capacidad. Para contratos completos amplios, solicita explícitamente level: "tools" y expand: ["options", "response", "examples"]. Las URL proporcionan descubrimiento contextual sin obtener la página. Los resultados de las herramientas omiten los precios de crédito por capacidad a menos que se establezca includeCosts: true; los argumentos de seguimiento nextTool lo conservan.

Los resultados están en data.alexandria[0].data. Sigue el nextTool de un elemento llamando a su name con su arguments; el nextTool de la página avanza la paginación. Los objetos next existentes siguen siendo llamadas de descubrimiento de Alexandria utilizables mediante firecrawl_scrape. El descubrimiento cuesta cero créditos y nunca ejecuta las herramientas del proveedor. Lee el contrato completo seleccionado antes de la ejecución.

Estos controles requieren el despliegue correspondiente de la API de Alexandria.

Ejecutar (firecrawl_scrape con alexandria): pasa alexandria en lugar de url (exactamente uno de los dos; también se pueden proporcionar requestId y timeout). Se acepta una sola llamada o un array de hasta diez llamadas.

{
  "name": "firecrawl_scrape",
  "arguments": {
    "alexandria": [
      {
        "provider": "fred",
        "capability": "series/observations",
        "options": { "series_id": "CPIAUCSL" }
      }
    ]
  }
}

Devuelve: { success, scrape_id, requestId, data: { alexandria: [...], creditsCost } }. Cada elemento es un resultado (provider, capability, data, records, upstreamStatus) o un error con un code; el lote nunca falla en su conjunto por un error de un proveedor y data.creditsCost es el total cobrado por la solicitud. Los cuerpos de error de Alexandria (403 sin acceso a Alexandria, y estados de facturación 402/409) se retransmiten en banda con su code.

La ejecución genera un x-request-id y lo devuelve tanto en caso de éxito como de fallo. Reintenta con la misma carga útil idéntica y ese requestId; no crees un nuevo ID tras un resultado incierto. La API comprueba los créditos disponibles.

Un proveedor de Alexandria cuyos términos el equipo no ha aceptado falla antes de que se ejecute nada con HTTP 403 y este cuerpo:

{
  "success": false,
  "code": "THIRD_PARTY_DATA_TERMS_REQUIRED",
  "error": "An organization admin must accept the benzinga provider's terms (version 2026-09-12-placeholder) before this request can run. Accept them at https://www.firecrawl.dev/app/alexandria/benzinga",
  "requiresAction": {
    "type": "accept_terms",
    "terms": "benzinga",
    "version": "2026-09-12-placeholder",
    "url": "https://www.firecrawl.dev/app/alexandria/benzinga"
  }
}

El resultado de la herramienta lo retransmite como un error con structuredContent que contiene code, status: 403, requestId, el objeto requiresAction sin cambios y next_actions (human_action_required y luego retry_same_request). Aceptar los términos es un acto legal, por lo que un administrador de la organización los acepta en el panel de Firecrawl, no a través del MCP. Usa la llamada nextTool devuelta para leer el acuerdo mediante firecrawl_scrape con alexandria: [{provider: "firecrawl", capability: "terms/show", options: {provider: "<provider>"}}], enviada por separado de la ejecución del proveedor, y preséntalo al usuario. Un administrador de la organización luego lo acepta en requiresAction.url, o en https://www.firecrawl.dev/app/settings?tab=data-sources. firecrawl_scrape rechaza cualquier otra capacidad de terms/*, por lo que no realiza cambios en la cuenta. Una solicitud de datos no es consentimiento, y no se produce ninguna aceptación automática ni reintentos inciertos. No se cobran créditos por la recuperación bloqueada. Después de que el administrador confirme la aceptación, llama a la misma herramienta de nuevo con la carga útil idéntica y requestId.

16. Herramienta de uso de créditos

La herramienta requiere una cuenta de Firecrawl autenticada y es de solo lectura.

• firecrawl_credit_usage toma el valor { "view": "current" } por defecto y devuelve remainingCredits, planCredits, billingPeriodStart y billingPeriodEnd. Los créditos restantes pueden superar los créditos del plan cuando el equipo tiene recargas o asignaciones.
• Pasa { "view": "historical" } para períodos de mes calendario que contienen startDate, endDate y creditsUsed. Pasar { "byApiKey": true } también selecciona la vista histórica y divide los períodos por clave de API; cada fila incluye entonces apiKey. Pasar { "byEndpoint": true } en su lugar divide los períodos por el endpoint que usó los créditos (scrape, search, crawl, map, agent, ...); cada fila incluye entonces endpoint. Pasa { "bin": "day" } para un período por día UTC en lugar de por mes calendario. No combines byApiKey con byEndpoint, ni ninguno de estos con { "view": "current" }. El endDate del período más reciente puede ser null. Si la API de Firecrawl aún no ofrece la división por endpoint ni los períodos diarios, el resultado incluye un notice y cifras mensuales.

Uso programático (inestable)

El paquete también expone un punto de entrada de biblioteca para incrustar el servidor en otro entorno de ejecución. Es inestable: la API, sus opciones y sus tipos pueden cambiar en cualquier versión, incluidas las versiones menores y de parche, así que fija una versión exacta.

npm install --save-exact firecrawl-mcp zod

El ejemplo define los parámetros de las herramientas con zod, por lo que el proyecto de incrustación lo instala como su propia dependencia.

import { createFirecrawlMcpServer } from 'firecrawl-mcp/server';
import { z } from 'zod';

const server = createFirecrawlMcpServer({
  transport: 'httpStream',
  apiKey: process.env.FIRECRAWL_API_KEY,
  unstable_hooks: {
    registerExtraTools: (registrar) => {
      registrar.addTool({
        name: 'my_tool',
        description: 'An extra tool served next to the Firecrawl tools.',
        parameters: z.object({ text: z.string() }),
        execute: async ({ text }) => text,
      });
    },
  },
});

await server.start({
  transportType: 'httpStream',
  httpStream: { port: 3000, host: '127.0.0.1', endpoint: '/mcp', stateless: true },
});
// MCP endpoint: http://127.0.0.1:3000/mcp

Establece host explícitamente. Sin él, el servidor escucha en localhost, que Node vincula a una sola dirección (a menudo solo ::1), por lo que las solicitudes a 127.0.0.1 se rechazan. Usa 0.0.0.0 o :: para aceptar conexiones de otras máquinas solo detrás de controles de acceso de red o de una comprobación de unstable_hooks.authenticate: sin una, todo llamador que pueda alcanzar el puerto recibe el servicio con el apiKey configurado.

La biblioteca no comprueba Host ni Origin a menos que se le pida, y sus cabeceras CORS permiten cualquier origen. Un servidor accesible desde un navegador en la misma máquina debería pasar httpStream.allowedHosts (por ejemplo, ['localhost', '127.0.0.1', '[::1]']): las solicitudes cuyo encabezado Host o Origin nombre otro host reciben entonces 403 (excepto GET y HEAD en la ruta de salud), y las cabeceras CORS repiten el origen permitido. La línea de comandos establece esta lista en el modo HTTP local.

Las opciones reflejan las variables de entorno de la CLI: apiUrl, apiKey, transport, logging, safeMode, fileAccess (local o upload), requireCredential, searchFeedback y endpointFeedback. unstable_hooks acepta:

Hook	Propósito
authenticate(request)	Resuelve la sesión de una solicitud; lanza un Response para rechazarla.
wrapTool(tool)	Decora cada herramienta registrada.
onToolResult(event)	Observa el inicio y el resultado de cada llamada a herramienta.
instructions	Instrucciones del servidor, o una función que elige entre las predeterminadas.
registerExtraTools(registrar, context)	Añade herramientas después de las integradas.
outboundRequest(session)	Credenciales y cabeceras adicionales para cada solicitud a la API de Firecrawl.
beforeKeylessRequest(session, origin)	Rechaza una solicitud sin clave lanzando una excepción.
toolFilter(name)	Deja las herramientas integradas fuera de la instancia.
configureHttp(app)	Añade rutas HTTP.
oauth.protectedResource	Sirve los metadatos del recurso protegido por OAuth.

El servidor se basa en el SDK oficial de TypeScript para MCP (@modelcontextprotocol/server). Usa los tipos exportados desde firecrawl-mcp/server (Session, ToolDefinition, ToolRegistrar, FirecrawlMcpServerHooks y otros) en lugar de los del propio SDK.

El punto de entrada también exporta los helpers que usan las herramientas integradas, como recoveryPayload, normalizeHeader, requestOrigin, isRuntimeUserAgent, initializeClientSlug, searchToolBaseFields, searchOutputSchema y structuredCompact, para que las herramientas y los hooks adicionales puedan coincidir con el comportamiento integrado. También son inestables.

Sistema de registro

El servidor incluye un registro completo:

• Estado y progreso de las 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 ofrece un manejo de errores robusto:

• Errores de límite de velocidad 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

Contribuir

1. Haz un fork del repositorio
2. Crea tu rama de funcionalidad
3. Ejecuta las pruebas: npm test
4. Envía una pull request

Gracias 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

Datos estructurados y resultados grandes

La búsqueda autenticada usa por defecto resultados web, herramientas semánticas de Alexandria y coincidencias de dominio. Empieza con la pregunta real. Usa firecrawl_find_tools para la búsqueda directa de herramientas semánticas, contratos seleccionados o navegación progresiva: categorías → proveedores → herramientas compactas → contrato seleccionado. Ejecuta las herramientas mediante firecrawl_scrape; el scraping de URL y la búsqueda ordinarios nunca ejecutan automáticamente herramientas de proveedores.

Para los contratos seleccionados, prefiere expand: ["options", "response"] y solicita ejemplos solo si la forma de la entrada no está clara. Inspecciona las capacidades relacionadas en conjunto y reutiliza los contratos devueltos.

Para un resultado de flujo de trabajo potencialmente grande, proporciona y conserva un requestId de nivel superior antes de la ejecución. Ese ID sigue disponible aunque el cliente rechace la respuesta. Los scrapes de URL normales usan en su lugar el ID de scrape devuelto.

Para un resultado grande de flujo de trabajo retenido o de scrape normal, llama a firecrawl_scrape con:

{
  "alexandria": {
    "provider": "firecrawl",
    "capability": "bash",
    "options": {
      "requestId": "<source-request-or-scrape-id>",
      "command": "ls -lh"
    }
  }
}

Lee stdout, stderr, exitCode y workspaceId en data.alexandria[0].data. Continúa con options: {workspaceId, command} para inspeccionar response.json usando jq, o document.md usando comandos de texto acotados para scrapes normales. Mantén la salida selectiva. La carga de la fuente debe ser una llamada independiente; su ID de fuente anidado difiere del ID de solicitud de ejecución de nivel superior. Los espacios de trabajo caducan tras cinco minutos de inactividad, y no todos los resultados se retienen (incluidos los payloads de flujos de trabajo de ZDR y de proveedores de API). No se admiten los ID de búsqueda.

Para las fuentes de flujo de trabajo, response.json conserva el sobre de la API: selecciona .data.alexandria[].data, luego el response.key del contrato seleccionado cuando no esté vacío. Combina los recuentos y proyecciones relacionados en un solo comando Bash cuando esa forma sea conocida, en lugar de inspeccionar las claves repetidamente.

Las respuestas exitosas de ejecución de Alexandria por encima de 20.000 tokens estimados (bytes UTF-8 serializados divididos entre cuatro) devuelven un pequeño traspaso después de que el Bash remoto confirme que el lote completo es accesible. Sigue nextTool para inspeccionar los datos retenidos. Esto añade una llamada a Bash e inicia un espacio de trabajo con un TTL de inactividad de cinco minutos. El payload completo se conserva. Si la confirmación falla, la respuesta original permanece en línea. La búsqueda, el scrape de URL normal, las respuestas de error y las llamadas de utilidad de Firecrawl no cambian. Este presupuesto de entrega no mide el contexto restante del cliente; no se añade ninguna caché de resultados local al proceso. Cuando hay herramientas de sistema de archivos locales disponibles, guardar la salida de la CLI y leer secciones seleccionadas es otra opción.

La secuencia de descubrimiento de la CLI se corresponde con estas llamadas MCP:

Intención	Herramienta	Argumentos
Herramientas web + semánticas + de dominio	firecrawl_search	{"query":"<user question>"}
Solo herramientas semánticas	firecrawl_search	{"query":"<user question>","sources":["alexandria"]}
Categorías	firecrawl_find_tools	{}
Proveedores en una categoría	firecrawl_find_tools	{"categories":["<category-id>"]}
Herramientas compactas de proveedor	firecrawl_find_tools	{"providers":["<provider-id>"]}
Contrato seleccionado	firecrawl_find_tools	{"providers":["<provider-id>"],"capabilities":["<capability-id>"]}
Ejecutar	firecrawl_scrape	{"alexandria":{"provider":"<provider-id>","capability":"<capability-id>","options":{"<required-field>":"<value>"}}}

Find Tools y la ejecución están disponibles tanto en la superficie completa como en la superficie de búsqueda. Reutiliza un contrato completo de la búsqueda cuando esté presente en lugar de hacer otra llamada de descubrimiento. Sigue la navegación de nextTool devuelta solo cuando se necesiten más resultados.

Comentarios de sesión de Alexandria

La herramienta existente firecrawl_feedback acepta endpoint: "alexandria":

{
  "endpoint": "alexandria",
  "rating": "partial",
  "requestedWebsite": {
    "url": "https://example.com",
    "requestedFunctionality": "Find records and download their attachments"
  },
  "objective": "Compare contract requirements across agencies before bidding",
  "rationale": "Found summaries but could not retrieve attachments"
}

El objective opcional es el objetivo subyacente de la sesión: lo que el agente o su usuario intentaba lograr en última instancia, más allá del sitio web único en requestedWebsite.

Esto usa POST /v2/feedback autenticado, sin un ID de trabajo. Debe llegar dentro de los 20 minutos posteriores a la búsqueda, el descubrimiento o la ejecución más recientes de Alexandria del equipo; los comentarios posteriores se rechazan con FEEDBACK_WINDOW_EXPIRED. Los comentarios elegibles pueden reembolsar 1 crédito, sujeto a límites diarios de 10 créditos por sitio web y 100 créditos por equipo (día UTC). Superado cualquiera de los límites, los comentarios se siguen registrando sin reembolso, y la respuesta establece websiteCapReached o dailyCapReached. Los arrays opcionales providerFeedback y capabilityFeedback describen lagunas de cobertura y problemas de ejecución; el esquema de la herramienta enumera los valores de problema admitidos. Un new_capability_request requiere requestedFunctionality; missing_capability (el proveedor existe pero carece de la capacidad) no. Se aplican los controles existentes de exclusión de comentarios y de autenticación.

Los resultados elegibles de ejecución y descubrimiento de Alexandria incluyen un puntero feedbackTool con el nombre de la herramienta y un esqueleto de los argumentos. El puntero se omite para las llamadas internas de Firecrawl como bash y cuando firecrawl_feedback no está registrado (FIRECRAWL_NO_ENDPOINT_FEEDBACK o inicio sin clave).