DEV Community

Cover image for Comment utiliser Firecrawl Local avec Claude Code et Cursor (MCP)
Antoine Laurent
Antoine Laurent

Posted on Originally published at apidog.com

Comment utiliser Firecrawl Local avec Claude Code et Cursor (MCP)

Pour utiliser Firecrawl Local, installez-le avec cargo install firecrawl-local, exécutez firecrawl-local init pour l'enregistrer comme serveur MCP dans Claude Code et Cursor, puis redémarrez ces deux outils. Votre agent peut désormais scraper, crawler et mapper des sites directement sur votre machine. Côté code, lancez firecrawl-local serve et pointez n'importe quel SDK Firecrawl vers http://localhost:3002.

Essayez Apidog dès aujourd'hui

Ce guide montre comment utiliser Firecrawl Local étape par étape, avec les vraies sorties de notre test du 19 novembre 2026 (Firecrawl Local 0.1.0 sur un Mac arm64), ainsi que les prompts à donner à votre agent et un moyen de laisser cet agent tester l'API locale avec Apidog CLI.

Ce qu'il vous faut avant de commencer

Firecrawl Local est un binaire Rust unique issu du dépôt Firecrawl. Avant de l'installer, vérifiez que vous disposez de :

  1. Rust et un compilateur C. Récupérez Rust sur rustup.rs. Sous macOS, exécutez xcode-select --install ; sous Debian ou Ubuntu, installez build-essential.
  2. Node.js 22 ou plus récent si vous voulez le serveur MCP. Il exécute le paquet npm firecrawl-mcp via npx.
  3. Chrome ou Chromium (facultatif). Firecrawl Local utilise le navigateur que vous avez déjà installé pour les pages qui nécessitent JavaScript. Les pages statiques fonctionnent sans.
  4. Claude Code, Cursor ou un autre client MCP. init connaît aussi Claude Desktop, Windsurf, Gemini CLI et Codex.

Si vous débutez avec Firecrawl lui-même, commencez par notre guide de scraping web avec Firecrawl, puis revenez.

Étape 1 : installez Firecrawl Local

Installez le crate depuis crates.io et vérifiez la version :

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

Cargo le compile depuis les sources. Sur notre Mac, la compilation en mode release a pris 6 minutes et 54 secondes, et le binaire s'est retrouvé dans ~/.cargo/bin/firecrawl-local. Assurez-vous que ce dossier figure dans votre PATH, ou notez le chemin complet : vous en aurez besoin pour configurer MCP manuellement.

Étape 2 : effectuez un premier scrape depuis le terminal

Avant de brancher quoi que ce soit dans un agent, vérifiez que la récupération fonctionne :

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

Il a affiché le texte principal de la page en markdown en 1,2 seconde. Retirez --markdown et vous obtenez le même JSON que renvoie l'API Firecrawl. --format markdown,links choisit les formats ; localement, les options sont markdown, html, rawHtml et links.

Ensuite, un crawl qui écrit un fichier markdown par page :

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

Cela a récupéré 20 pages de la documentation Firecrawl en 4,4 secondes et enregistré des fichiers nommés comme 0005-docs.firecrawl.dev_advanced-scraping-guide.md. Options utiles de firecrawl-local crawl --help :

Option Ce que ça fait
-l, --limit Nombre maximal de pages (100 par défaut)
--max-depth Profondeur de liens à suivre
--include, --exclude Expression régulière de chemin à conserver ou ignorer, répétable
--entire-domain Suivre les liens en dehors du chemin de départ
-c, --concurrency Nombre de pages récupérées simultanément
--ignore-robots Ignorer robots.txt (lu par défaut)

firecrawl-local map https://firecrawl.dev renvoie toutes les URL trouvées dans les sitemaps et sur la page de départ, sur une seule ligne JSON.

Étape 3 : ajoutez Firecrawl Local à Claude Code et Cursor avec init

init détecte les outils d'IA présents sur votre machine et ajoute Firecrawl Local à la configuration MCP de chacun. Vous pouvez d'abord faire un aperçu :

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

Sur notre Mac, il a listé tous les outils qu'il allait modifier :

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

Le dry run affiche aussi ce qui est envoyé à Firecrawl Cloud : les requêtes de recherche, l'URL d'une page qui a bloqué votre machine, les appels à Alexandria une fois connecté, ainsi qu'un identifiant d'installation aléatoire et le nom de votre outil d'IA. Les pages qui se chargent correctement en local ne sont jamais envoyées.

Pour ne configurer que les deux outils couverts par ce guide, répétez --agent :

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

Les noms valides sont claude-code, claude-desktop, cursor, windsurf, gemini et codex. init sauvegarde chaque fichier de configuration avant de l'écrire. Redémarrez ensuite Claude Code et Cursor pour qu'ils chargent le nouveau serveur.

Claude Code and Cursor talk to firecrawl-local mcp over stdio; it scrapes, crawls and maps on your machine and only sends search and blocked pages to Firecrawl Cloud unless FIRECRAWL_CLOUD=off

Configurer Firecrawl Local dans Claude Code à la main

Si vous préférez ne pas laisser un outil modifier vos configurations, ajoutez vous-même le serveur stdio avec la commande 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

Exécutez /mcp dans Claude Code pour confirmer que le serveur est bien connecté.

Configurer Firecrawl Local dans Cursor à la main

Cursor lit les serveurs MCP depuis ~/.cursor/mcp.json (global) ou .cursor/mcp.json (un projet). Utilisez le chemin complet vers le binaire :

{
  "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 fait refuser au serveur les adresses localhost et de réseau privé. Gardez cette option active lorsque votre agent lit des pages auxquelles vous ne faites pas confiance : des instructions cachées sur une page pourraient sinon orienter l'agent vers une URL interne.

Étape 4 : prompts à donner à votre agent

firecrawl-local mcp démarre l'API locale sur un port de loopback et exécute le paquet firecrawl-mcp en s'y connectant. Votre agent voit les outils MCP Firecrawl standards ; scrape, crawl, map et batch scrape s'exécutent sur votre machine. Si vous avez déjà utilisé le serveur MCP Firecrawl hébergé, les noms d'outils sont identiques.

Des prompts adaptés aux outils locaux :

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

Évitez les prompts qui nécessitent la recherche : avec FIRECRAWL_CLOUD=off, cet outil ne va nulle part. Pour une configuration de recherche entièrement locale, consultez notre guide sur la recherche web open source pour Claude.

Étape 5 : lancez l'API Firecrawl Local et pointez votre SDK vers elle

Pour les scripts et pipelines, lancez le serveur API :

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

Il écoute sur 127.0.0.1:3002. Le health check répond immédiatement :

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

Un scrape renvoie la structure v2 familière, avec deux marqueurs locaux : "engine": "local-fetch" et "source": "local", plus 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

Pointez les SDK Firecrawl vers elle, sans clé API. 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 suggère aussi un raccourci : définissez FIRECRAWL_API_URL=http://127.0.0.1:3002 et votre code Firecrawl existant s'exécute localement. La CLI Firecrawl partage sa session sauvegardée avec Firecrawl Local, donc le login de l'un fonctionne pour les deux.

Les crawls sont asynchrones. POST /v2/crawl a renvoyé immédiatement un identifiant de tâche, et GET /v2/crawl/{id} a rapporté status: completed, total: 10, creditsUsed: 0 et expiresInSeconds: 3587 quelques secondes plus tard. Les tâches vivent en mémoire, expirent une heure après leur démarrage et disparaissent à l'arrêt de serve ; sauvegardez donc les résultats dès qu'un crawl se termine.

Le processus serveur occupait environ 10 Mo de mémoire résidente au repos et 43 Mo juste après ce crawl de 10 pages, mesurés avec ps. Le billet de lancement de Firecrawl revendique une rapidité 37 fois supérieure et une consommation mémoire 230 fois moindre que Firecrawl auto-hébergé ; le README ne publie aucune méthode, considérez donc ces chiffres comme ceux de Firecrawl.

Garder Firecrawl Local entièrement local avec FIRECRAWL_CLOUD

Par défaut (auto), trois choses sont envoyées à Firecrawl Cloud : la recherche, les pages qui bloquent votre machine, et les fournisseurs de données Alexandria (qui nécessitent un compte gratuit via firecrawl-local login). FIRECRAWL_CLOUD contrôle le transfert :

Valeur Effet
auto (par défaut) La recherche, le repli sur les pages bloquées et Alexandria fonctionnent tous
search Seule la recherche est envoyée à Firecrawl Cloud
off Rien n'est envoyé à Firecrawl Cloud

Une valeur non reconnue est traitée comme off. Avec le cloud désactivé, POST /v2/search répond "code":"CLOUD_ONLY" avec un message vous invitant à définir FIRECRAWL_API_KEY ou FIRECRAWL_CLOUD=auto. Une page récupérée par le cloud porte "source": "firecrawl-cloud", vous pouvez donc toujours savoir d'où vient un résultat.

serve refuse les cibles localhost et privées à moins de passer --allow-private, et lier un --host non-loopback nécessite --token. Les adresses de métadonnées cloud et link-local sont bloquées dans tous les modes.

Laissez votre agent de codage tester l'API Firecrawl Local avec Apidog CLI

L'endpoint de crawl est celui qui a le plus de chances de casser un pipeline : il est asynchrone, la tâche expire, et un serveur arrêté la perd. Plutôt que d'interroger manuellement en boucle, laissez votre agent de codage construire et exécuter un test avec Apidog CLI.

Configurez-le une fois :

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

Donnez ensuite un prompt à Claude Code ou 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

Sequence of the agent-built test: Apidog CLI posts /v2/crawl to firecrawl-local serve, polls GET /v2/crawl/{id} until completed, checks the assertions and writes a cli, json or junit report

L'agent lit chaque schéma de payload, le valide et exécute des commandes comme celles-ci, toutes tirées de apidog <cmd> --help dans 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 envoie les requêtes depuis votre machine, donc localhost:3002 est accessible. Passez à -r junit pour intégrer la même exécution à votre CI ; nos guides sur Apidog CLI dans Claude Code et Apidog CLI dans Cursor couvrent le côté agent. Le plan gratuit d'Apidog couvre les équipes jusqu'à 4 utilisateurs.

Dépannage de Firecrawl Local

Symptôme Correctif
404 avec NOT_FOUND sur /v1/scrape Seule la v2 est servie ; configurez votre client sur /v2/...
CLOUD_ONLY sur /v2/search Attendu avec FIRECRAWL_CLOUD=off ; utilisez auto ou search
L'agent ne liste pas les outils Firecrawl Redémarrez l'outil après init ; vérifiez Node.js 22+
Une page JavaScript revient trop maigre Installez Chrome, ou passez --browser always
Format json ou summary manquant Non pris en charge localement ; vous recevez un avertissement
ID de crawl introuvable La tâche a expiré au bout d'une heure ou serve a redémarré

FAQ

Firecrawl Local est-il gratuit ? Le scraping, le crawl et le mapping locaux n'envoient rien à Firecrawl et ont utilisé 0 crédit dans nos tests. Le code est sous AGPL-3.0 ; les SDK sous MIT. La recherche et Alexandria passent par Firecrawl Cloud.

Ai-je besoin d'une clé API pour utiliser Firecrawl Local ? Non, pas pour les routes locales. Vous n'en avez besoin, via firecrawl-local login ou FIRECRAWL_API_KEY, que pour les fournisseurs de données Alexandria.

Firecrawl Local fonctionne-t-il avec Windsurf, Codex et Gemini CLI ? Oui. init connaît windsurf, codex et gemini, tout comme Claude Code, Claude Desktop et Cursor.

Mon code Firecrawl existant peut-il tourner dessus sans modification ? Pour scrape, map, crawl et batch scrape en v2, oui : changez l'URL de l'API en http://localhost:3002. Les routes v0 et v1 ne sont pas servies, et les actions du navigateur sont ignorées.

Firecrawl Local respecte-t-il robots.txt ? Oui. Il lit robots.txt lors du crawl et s'identifie dans son User-Agent, ce qui permet aux propriétaires de sites de le reconnaître en tant que FirecrawlLocal. --ignore-robots désactive ce comportement ; n'utilisez cette option que sur des sites que vous possédez.

Top comments (0)