DEV Community

Cover image for Cómo usar Firecrawl Local con Claude Code y Cursor (MCP)
Roobia
Roobia

Posted on Originally published at apidog.com

Cómo usar Firecrawl Local con Claude Code y Cursor (MCP)

Para usar Firecrawl Local, instálalo con cargo install firecrawl-local, ejecuta firecrawl-local init para registrarlo como servidor MCP en Claude Code y Cursor, y luego reinicia ambas herramientas. Tu agente ya puede hacer scraping, crawling y mapping de sitios en tu propia máquina. Para usarlo desde código, ejecuta firecrawl-local serve y apunta cualquier SDK de Firecrawl a http://localhost:3002.

Prueba Apidog hoy

Esta guía muestra cómo usar Firecrawl Local paso a paso, con la salida real de nuestra prueba del 19 de noviembre de 2026 (Firecrawl Local 0.1.0 en un Mac arm64), además de los prompts que puedes darle a tu agente y una forma de que ese agente pruebe la API local con Apidog CLI.

Lo que necesitas antes de empezar

Firecrawl Local es un único binario de Rust del repositorio de Firecrawl. Antes de instalarlo, comprueba que tienes:

  1. Rust y un compilador de C. Consigue Rust en rustup.rs. En macOS ejecuta xcode-select --install; en Debian o Ubuntu instala build-essential.
  2. Node.js 22 o superior si quieres el servidor MCP. Ejecuta el paquete npm firecrawl-mcp mediante npx.
  3. Chrome o Chromium (opcional). Firecrawl Local usa el navegador que ya tienes para las páginas que necesitan JavaScript. Las páginas estáticas funcionan sin él.
  4. Claude Code, Cursor u otro cliente MCP. init también reconoce Claude Desktop, Windsurf, Gemini CLI y Codex.

Si eres nuevo en Firecrawl, empieza por nuestra guía de web scraping con Firecrawl y vuelve después.

Paso 1: Instalar Firecrawl Local

Instala el crate desde crates.io y confirma la versión:

cargo install firecrawl-local
firecrawl-local --version
# firecrawl-local 0.1.0
Enter fullscreen mode Exit fullscreen mode

Cargo lo compila desde el código fuente. En nuestro Mac, la build de release terminó en 6 minutos y 54 segundos, y el binario quedó en ~/.cargo/bin/firecrawl-local. Asegúrate de que esa carpeta esté en tu PATH o anota la ruta completa: la necesitarás para configurar el MCP manualmente.

Paso 2: Haz tu primer scrape desde la terminal

Antes de conectar nada a un agente, comprueba que la descarga funciona:

FIRECRAWL_CLOUD=off firecrawl-local scrape https://example.com --markdown
Enter fullscreen mode Exit fullscreen mode

Imprimimos el texto principal de la página en markdown en 1,2 segundos. Si quitas --markdown, obtendrás el mismo JSON que devuelve la API de Firecrawl. --format markdown,links selecciona los formatos; las opciones locales son markdown, html, rawHtml y links.

A continuación, un crawl que escribe un archivo markdown por página:

FIRECRAWL_CLOUD=off firecrawl-local crawl https://docs.firecrawl.dev --limit 20 --out ./pages
Enter fullscreen mode Exit fullscreen mode

Esto descargó 20 páginas de la documentación de Firecrawl en 4,4 segundos y guardó archivos con nombres como 0005-docs.firecrawl.dev_advanced-scraping-guide.md. Flags útiles de crawl de firecrawl-local crawl --help:

Flag Qué hace
-l, --limit Máximo de páginas (por defecto 100)
--max-depth Cuántos enlaces de profundidad seguir
--include, --exclude Regex de ruta para mantener u omitir, repetible
--entire-domain Seguir enlaces fuera de la ruta inicial
-c, --concurrency Páginas descargadas a la vez
--ignore-robots Omitir robots.txt (por defecto se lee)

firecrawl-local map https://firecrawl.dev devuelve cada URL que encuentra en los sitemaps y la página inicial, en una sola línea JSON.

Paso 3: Añade Firecrawl Local a Claude Code y Cursor con init

init detecta las herramientas de IA de tu máquina y añade Firecrawl Local a la configuración MCP de cada una. Previsualízalo primero:

firecrawl-local init --dry-run
Enter fullscreen mode Exit fullscreen mode

En nuestro Mac, enumeró cada herramienta que modificaría:

Firecrawl MCP server:
  Claude Code: would be added in ~/.claude.json
  Claude desktop: would be added in ~/Library/Application Support/Claude/claude_desktop_config.json
  Cursor: would be added in ~/.cursor/mcp.json
  Gemini CLI: would be added in ~/.gemini/settings.json
  Codex: would be added in ~/.codex/config.toml
Enter fullscreen mode Exit fullscreen mode

El dry run también muestra qué se envía a Firecrawl Cloud: las consultas de búsqueda, la URL de una página que bloqueó tu máquina, las llamadas a Alexandria cuando inicias sesión, y un ID de instalación aleatorio junto con el nombre de tu herramienta de IA. Las páginas que se cargan bien en local nunca se envían.

Para configurar solo las dos herramientas que cubre esta guía, repite --agent:

firecrawl-local init --agent claude-code --agent cursor
Enter fullscreen mode Exit fullscreen mode

Los nombres válidos son claude-code, claude-desktop, cursor, windsurf, gemini y codex. init hace una copia de seguridad de cada archivo de configuración antes de escribir. Reinicia Claude Code y Cursor después para que carguen el nuevo servidor.

Claude Code y Cursor se comunican con firecrawl-local mcp por stdio; hace scraping, crawling y mapping en tu máquina y solo envía búsquedas y páginas bloqueadas a Firecrawl Cloud salvo que FIRECRAWL_CLOUD=off

Firecrawl Local en Claude Code manualmente

Si prefieres no dejar que una herramienta edite tu configuración, añade tú mismo el servidor stdio con el comando MCP de Claude Code:

claude mcp add firecrawl -e FIRECRAWL_CLOUD=off -- ~/.cargo/bin/firecrawl-local mcp --public-only
Enter fullscreen mode Exit fullscreen mode

Ejecuta /mcp dentro de Claude Code para confirmar que el servidor está conectado.

Firecrawl Local en Cursor manualmente

Cursor lee los servidores MCP de ~/.cursor/mcp.json (global) o .cursor/mcp.json (un proyecto). Usa la ruta completa al binario:

{
  "mcpServers": {
    "firecrawl": {
      "command": "/Users/you/.cargo/bin/firecrawl-local",
      "args": ["mcp", "--public-only"],
      "env": { "FIRECRAWL_CLOUD": "off" }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

--public-only hace que el servidor rechace localhost y direcciones de red privada. Mantenlo activo cuando tu agente lea páginas en las que no confías: en caso contrario, las instrucciones ocultas de una página podrían dirigir al agente hacia una URL interna.

Paso 4: Prompts para darle a tu agente

firecrawl-local mcp inicia la API local en un puerto de loopback y ejecuta el paquete firecrawl-mcp contra ella. Tu agente ve las herramientas MCP estándar de Firecrawl; scrape, crawl, map y batch scrape se ejecutan en tu máquina. Si ya has usado el servidor MCP de Firecrawl alojado, los nombres de las herramientas son los mismos.

Prompts que encajan bien con las herramientas locales:

Map https://docs.example.com, then crawl only the /api/ pages (limit 40)
and write a summary of every endpoint into docs/vendor-api.md.
Enter fullscreen mode Exit fullscreen mode
Scrape the changelog at https://example.com/changelog as markdown and list
every breaking change from the last three releases.
Enter fullscreen mode Exit fullscreen mode
Batch scrape these five pricing pages and build a comparison table of
plan names and limits. Quote only what the pages say.
Enter fullscreen mode Exit fullscreen mode

Evita los prompts que necesiten búsqueda: con FIRECRAWL_CLOUD=off, esa herramienta no llega a ningún sitio. Para una configuración de búsqueda totalmente local, consulta nuestra guía de búsqueda web de código abierto para Claude.

Paso 5: Ejecuta la API local de Firecrawl y apunta tu SDK a ella

Para scripts y pipelines, ejecuta el servidor de la API:

FIRECRAWL_CLOUD=off firecrawl-local serve
Enter fullscreen mode Exit fullscreen mode

Escucha en 127.0.0.1:3002. El health check responde de inmediato:

curl -s localhost:3002/health
# {"status":"ok","engine":"firecrawl-local","version":"0.1.0"}
Enter fullscreen mode Exit fullscreen mode

Un scrape devuelve la conocida forma v2, con dos marcadores locales dentro: "engine": "local-fetch" y "source": "local", además de creditsUsed: 0.

curl -s localhost:3002/v2/scrape -H 'content-type: application/json' \
  -d '{"url":"https://example.com","formats":["markdown","links"]}'
Enter fullscreen mode Exit fullscreen mode

Apunta los SDK de Firecrawl a ella sin API key. Python:

from firecrawl import Firecrawl

app = Firecrawl(api_url="http://localhost:3002")
print(app.scrape("https://example.com").markdown)
Enter fullscreen mode Exit fullscreen mode

Node:

import { Firecrawl } from "firecrawl";

const app = new Firecrawl({ apiUrl: "http://localhost:3002" });
const doc = await app.scrape("https://example.com");
console.log(doc.markdown);
Enter fullscreen mode Exit fullscreen mode

init también sugiere un atajo: define FIRECRAWL_API_URL=http://127.0.0.1:3002 y tu código existente de Firecrawl se ejecutará en local. La CLI de Firecrawl comparte su sesión guardada con Firecrawl Local, así que el login de cualquiera de las dos herramientas sirve para ambas.

Los crawls son asíncronos. POST /v2/crawl devolvió un job ID de inmediato, y GET /v2/crawl/{id} informó de status: completed, total: 10, creditsUsed: 0 y expiresInSeconds: 3587 unos segundos después. Los jobs viven en memoria, caducan una hora después de iniciarse y desaparecen cuando se detiene serve, así que guarda los resultados en cuanto termine un crawl.

El proceso del servidor se mantuvo en unos 10 MB de memoria residente en reposo y 43 MB justo después de ese crawl de 10 páginas, medido con ps. El post de lanzamiento de Firecrawl afirma que es 37 veces más rápido y usa 230 veces menos memoria que Firecrawl autoalojado; el README no publica el método, así que trátalas como cifras de Firecrawl.

Mantén Firecrawl Local completamente local con FIRECRAWL_CLOUD

Por defecto (auto), tres cosas van a Firecrawl Cloud: la búsqueda, las páginas que bloquean tu máquina y los proveedores de datos de Alexandria (que requieren una cuenta gratuita mediante firecrawl-local login). FIRECRAWL_CLOUD controla el traspaso:

Valor Efecto
auto (por defecto) Búsqueda, fallback de páginas bloqueadas y Alexandria funcionan
search Solo la búsqueda va a Firecrawl Cloud
off Nada va a Firecrawl Cloud

Un valor no reconocido cuenta como off. Con la nube desactivada, POST /v2/search responde "code":"CLOUD_ONLY" con un mensaje que te indica que definas FIRECRAWL_API_KEY o FIRECRAWL_CLOUD=auto. Una página que la nube descargó por ti lleva "source": "firecrawl-cloud", así que siempre puedes saber de dónde vino un resultado.

serve rechaza localhost y objetivos privados a menos que pases --allow-private, y para enlazar un --host que no sea loopback se requiere --token. Los metadatos de la nube y las direcciones link-local están bloqueados en todos los modos.

Deja que tu agente de código pruebe la API local de Firecrawl con Apidog CLI

El endpoint de crawl es el que más probablemente rompa un pipeline: es asíncrono, el job expira y si el servidor se detiene, se pierde. En lugar de hacer polling a mano, deja que tu agente de código cree y ejecute una prueba con Apidog CLI.

Configúralo una vez:

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_TOKEN>
apidog skill install
Enter fullscreen mode Exit fullscreen mode

Después dale un solo prompt a Claude Code o Cursor:

firecrawl-local serve is running on http://localhost:3002. In Apidog project <id>,
import an OpenAPI file for POST /v2/scrape, POST /v2/crawl and GET /v2/crawl/{id},
create an environment for that base URL, and build a test scenario that starts a
crawl of https://docs.firecrawl.dev with limit 10, saves the returned id, polls
GET /v2/crawl/{id} until status is "completed", and asserts total equals completed
and every page has non-empty markdown. Run it and summarize any failures.
Enter fullscreen mode Exit fullscreen mode

Secuencia de la prueba creada por el agente: Apidog CLI hace POST /v2/crawl a firecrawl-local serve, hace polling de GET /v2/crawl/{id} hasta que completa, comprueba las aserciones y escribe un informe cli, json o junit

El agente lee el esquema de cada payload, lo valida y ejecuta comandos como estos, todos tomados de apidog <cmd> --help en la CLI 2.2.12:

apidog import --project <id> --format openapi --file ./firecrawl-local-v2.yaml
apidog environment create firecrawl-local --project <id> --base-url http://localhost:3002
apidog cli-schema get test-scenario-create
apidog cli-schema validate test-scenario-create --file scenario.json
apidog test-scenario create --project <id> --file ./scenario.json
apidog run -t <scenarioId> --project <id> -e <envId> -r cli,json
Enter fullscreen mode Exit fullscreen mode

Apidog CLI envía solicitudes desde tu máquina, así que localhost:3002 es accesible. Cambia a -r junit para llevar la misma ejecución a CI; nuestras guías de Apidog CLI en Claude Code y Apidog CLI en Cursor cubren el lado del agente. El plan Free de Apidog cubre equipos de hasta 4 usuarios.

Solución de problemas de Firecrawl Local

Síntoma Solución
404 con NOT_FOUND en /v1/scrape Solo se sirve v2; cambia tu cliente a /v2/...
CLOUD_ONLY en /v2/search Es lo esperado con FIRECRAWL_CLOUD=off; usa auto o search
El agente no muestra las herramientas de Firecrawl Reinicia la herramienta después de init; comprueba que tienes Node.js 22+
Una página JavaScript devuelve poco contenido Instala Chrome o define --browser always
Falta el formato json o summary No están soportados en local; en su lugar recibirás un aviso
No se encuentra el crawl ID El job expiró tras una hora o serve se reinició

Preguntas frecuentes

¿Firecrawl Local es gratis? Las operaciones locales de scraping, crawling y mapping no envían nada a Firecrawl y consumieron 0 créditos en nuestras pruebas. El código es AGPL-3.0; los SDK son MIT. La búsqueda y Alexandria pasan por Firecrawl Cloud.

¿Necesito una API key para usar Firecrawl Local? No, no para las rutas locales. Solo necesitas una key, mediante firecrawl-local login o FIRECRAWL_API_KEY, para los proveedores de datos de Alexandria.

¿Firecrawl Local funciona con Windsurf, Codex y Gemini CLI? Sí. init reconoce windsurf, codex y gemini, además de Claude Code, Claude Desktop y Cursor.

¿Mi código existente de Firecrawl puede ejecutarse contra él sin cambios? Para scrape, map, crawl y batch scrape de v2, sí: cambia la URL de la API a http://localhost:3002. Las rutas v0 y v1 no se sirven, y las actions del navegador se ignoran.

¿Firecrawl Local respeta robots.txt? Sí. Lee robots.txt al hacer crawling y se identifica en su User-Agent, así que los propietarios de sitios pueden dirigirse a él como FirecrawlLocal. --ignore-robots lo desactiva; úsalo solo en sitios que sean tuyos.

Top comments (0)