Firecrawl MCP

Serveur MCP Firecrawl

Un serveur Model Context Protocol (MCP) qui apporte Firecrawl aux agents IA compatibles MCP — recherchez, scrapez et interagissez avec le web en direct pour obtenir un contexte propre et prêt pour les agents.

Un grand merci à @vrknetha, @knacklabs pour l'implémentation initiale !

Fonctionnalités

• Recherchez sur le web et obtenez le contenu complet des pages
• Recherchez dans un index conçu pour les agents de codage : issues GitHub, pull requests fusionnées, README et documentation
• Scrapez n'importe quelle URL pour obtenir des données propres et structurées
• Interagissez avec les pages — cliquez, naviguez et opérez
• Recherche approfondie avec agent autonome
• Nouvelles tentatives automatiques et limitation de débit
• Prise en charge cloud et auto-hébergée
• Prise en charge SSE

Testez notre serveur MCP sur le playground de MCP.so ou sur Klavis AI.

Quand Utiliser Ce Serveur

• Utilisez firecrawl_scrape lorsque vous avez une URL connue et souhaitez son contenu en markdown ou en JSON correspondant à un schéma que vous fournissez.
• Utilisez firecrawl_map lorsque vous devez découvrir des URLs sur un site sans récupérer leur contenu.
• Utilisez firecrawl_crawl lorsque vous avez besoin du contenu de nombreuses pages d'un site ; définissez limit, includePaths/excludePaths ou maxDiscoveryDepth pour le limiter.
• Utilisez firecrawl_search lorsque vous partez d'une requête plutôt que d'une URL et souhaitez des résultats web classés ; ajoutez scrapeOptions si vous souhaitez également que le contenu des pages soit récupéré dans le même appel (l'endpoint de recherche seule ne récupère jamais le contenu).
• Utilisez firecrawl_interact lorsqu'une page nécessite une action de clic, de saisie ou de navigation avant de pouvoir la lire — passez un url pour une nouvelle page ou un scrapeId pour continuer sur une page déjà scrapée.
• Utilisez les outils firecrawl_monitor_* lorsque la même page doit être vérifiée selon un calendrier récurrent avec des diffs et des alertes de changement, plutôt que récupérée une seule fois.
• Envisagez autre chose lorsque vous devez maintenir une session navigateur ouverte sur de nombreuses étapes de votre propre logique avec vos propres mécanismes de nouvelle tentative et de terminaison : chaque appel firecrawl_interact exécute un tour prompt ou code jusqu'à son terme et rend la main — la session peut persister entre les appels via scrapeId et se termine avec firecrawl_interact_stop, mais vous ne pouvez pas la piloter de manière interactive étape par étape côté client dans un seul appel.

Ce serveur répertorie 25 outils lorsque le profil complet s'enregistre avec les paramètres par défaut (outils de retour inclus, sans mode local sans clé). Définir FIRECRAWL_NO_SEARCH_FEEDBACK=1 et/ou FIRECRAWL_NO_ENDPOINT_FEEDBACK=1 supprime les outils de retour correspondants et réduit ce nombre, tout comme le démarrage local sans clé. Pour les clients avec une limite d'emplacements d'outils : l'endpoint hébergé sans clé (https://mcp.firecrawl.dev/v2/mcp, sans clé API) n'expose que 3 — firecrawl_scrape, firecrawl_search, firecrawl_parse — et l'endpoint dédié recherche seule (https://mcp.firecrawl.dev/v2/mcp-search) expose un ensemble fixe de 6 outils en lecture seule.

Installation

MCP hébergé (niveau gratuit sans clé)

Connectez-vous au serveur distant hébergé sans configuration :

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

Sur le niveau gratuit sans clé, scrape, search et parse fonctionnent sans clé API (avec limitation de débit). D'autres outils comme crawl, map et agent nécessitent toujours une clé.

Privilégiez OAuth ou une clé API lorsque l'humain peut s'inscrire. Cela débloque l'ensemble complet d'outils et des limites plus élevées.

Pour une connexion de compte interactive, configurez votre client MCP pour utiliser cette URL de serveur. C'est un endpoint MCP, pas une page navigateur ; utilisez le flux de connexion de compte du client et n'ajoutez pas une seconde entrée de serveur Firecrawl lors de la reconnexion :

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

Pour une connexion par clé API (par exemple, une intégration non supervisée), conservez l'URL du serveur comme suit :

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

Ensuite, configurez l'en-tête sécurisé ou le paramètre secret du client avec :

Authorization: Bearer <FIRECRAWL_API_KEY>

Ne mettez jamais une clé API dans l'URL du serveur. Ne mettez jamais une clé API dans un chat d'agent. Configurez-la directement dans le client ou le gestionnaire de secrets. Consultez le guide de configuration MCP hébergé et le guide d'intégration des agents pour des instructions spécifiques au client.

Endpoint recherche seule

Une surface en lecture seule, réservée à la recherche, est également hébergée à :

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

Elle expose un ensemble fixe de six outils en lecture seule : firecrawl_search, firecrawl_developer_search et les quatre outils firecrawl_research_*. Elle n'effectue aucune récupération de contenu de page et possède sa propre identité OAuth ; l'endpoint complet ci-dessus est inchangé. Voir docs/search-profile.md pour le contrat complet.

Exécution avec npx

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

Installation manuelle

npm install -g firecrawl-mcp

Exécution sur Cursor

Configuration de Cursor 🖥️ Remarque : nécessite Cursor version 0.45.6+ Pour les instructions de configuration les plus récentes, veuillez consulter la documentation officielle de Cursor sur la configuration des serveurs MCP : Guide de configuration des serveurs MCP de Cursor

Pour configurer Firecrawl MCP dans Cursor v0.48.6

1. Ouvrez les paramètres de Cursor
2. Allez dans Fonctionnalités > Serveurs MCP
3. Cliquez sur « + Ajouter un nouveau serveur MCP global »
4. Saisissez le code suivant :

   {
     "mcpServers": {
       "firecrawl-mcp": {
         "command": "npx",
         "args": ["-y", "firecrawl-mcp"],
         "env": {
           "FIRECRAWL_API_KEY": "YOUR-API-KEY"
         }
       }
     }
   }
   

Pour configurer Firecrawl MCP dans Cursor v0.45.6

1. Ouvrez les paramètres de Cursor
2. Allez dans Fonctionnalités > Serveurs MCP
3. Cliquez sur « + Ajouter un nouveau serveur MCP »
4. Saisissez ce qui suit :
   • Nom : « firecrawl-mcp » (ou le nom de votre choix)
   • Type : « commande »
   • Commande : env FIRECRAWL_API_KEY=your-api-key npx -y firecrawl-mcp

Si vous utilisez Windows et rencontrez des problèmes, essayez cmd /c "set FIRECRAWL_API_KEY=your-api-key && npx -y firecrawl-mcp"

Remplacez your-api-key par votre clé API Firecrawl. Si vous n'en avez pas encore, vous pouvez créer un compte et l'obtenir depuis https://www.firecrawl.dev/app/api-keys

Après l'ajout, actualisez la liste des serveurs MCP pour voir les nouveaux outils. L'agent Composer utilisera automatiquement Firecrawl MCP lorsque cela est approprié, mais vous pouvez le demander explicitement en décrivant vos besoins de scraping web. Accédez au Composer via Commande+L (Mac), sélectionnez « Agent » à côté du bouton d'envoi, et saisissez votre requête.

Exécution sur Windsurf

Ajoutez ceci à votre ./codeium/windsurf/model_config.json :

{
  "mcpServers": {
    "mcp-server-firecrawl": {
      "command": "npx",
      "args": ["-y", "firecrawl-mcp"],
      "env": {
        "FIRECRAWL_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Exécution avec le mode local Streamable HTTP

Pour exécuter le serveur en utilisant Streamable HTTP localement au lieu du transport stdio par défaut :

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

Utilisez l'URL : http://localhost:3000/mcp

Installation via Smithery (hérité)

Pour installer Firecrawl pour Claude Desktop automatiquement via Smithery :

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

Exécution sur VS Code

Pour une installation en un clic, cliquez sur l'un des boutons d'installation ci-dessous...

Pour une installation manuelle, ajoutez le bloc JSON suivant à votre fichier Paramètres utilisateur (JSON) dans VS Code. Vous pouvez le faire en appuyant sur Ctrl + Shift + P et en tapant 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}"
        }
      }
    }
  }
}

En option, vous pouvez l'ajouter à un fichier nommé .vscode/mcp.json dans votre espace de travail. Cela vous permettra de partager la configuration avec d'autres :

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

Configuration

Variables d'environnement

Requises pour l'API cloud

• FIRECRAWL_API_KEY : votre clé API Firecrawl
  • Requise lors de l'utilisation de l'API cloud (par défaut)
  • Optionnelle lors de l'utilisation d'une instance auto-hébergée avec FIRECRAWL_API_URL
• FIRECRAWL_API_URL (Optionnel) : endpoint API personnalisé pour les instances auto-hébergées
  • Exemple : https://firecrawl.your-domain.com
  • S'il n'est pas fourni, l'API cloud sera utilisée (nécessite une clé API)

OAuth MCP (jetons d'accès Bearer)

Firecrawl hébergé peut émettre des jetons d'accès OAuth (fco_…) via le serveur d'autorisation sur firecrawl.dev. Ce serveur MCP transmet la référence qu'il résout à l'API Firecrawl comme Authorization: Bearer ….

• Transports de flux HTTP (CLOUD_SERVICE=true, HTTP_STREAMABLE_SERVER=true ou SSE_LOCAL=true) : les clients doivent envoyer Authorization: Bearer <fco_access_token> sur les requêtes MCP. Un jeton porteur OAuth a priorité sur x-firecrawl-api-key / x-api-key lorsque les deux sont présents.
• stdio : Utilisez FIRECRAWL_OAUTH_TOKEN pour un jeton d'accès statique, ou continuez à utiliser FIRECRAWL_API_KEY pour une clé API.

Utilisez uniquement les jetons d'accès (fco_…). Les jetons de rafraîchissement (fcr_…) doivent être échangés au niveau de l'endpoint de jeton, et non transmis à l'API de scrape/recherche.

Surface recherche seule (hébergée)

En mode hébergé (CLOUD_SERVICE=true), une seconde instance en processus sert l'endpoint recherche seule. Le service groupé a un contrat de déploiement fixe : nginx route /v2/mcp-search vers l'instance sur le port local 3001, et l'identifiant de ressource protégée OAuth est https://mcp.firecrawl.dev/v2/mcp-search.

FIRECRAWL_MCP_SEARCH_ENABLED (par défaut true) est l'interrupteur opérationnel pris en charge ; définissez-le sur false pour empêcher le démarrage de l'instance de recherche. Le processus Node accepte également FIRECRAWL_MCP_SEARCH_PORT, FIRECRAWL_MCP_SEARCH_ENDPOINT et FIRECRAWL_MCP_SEARCH_RESOURCE_URL pour les tests isolés. Ces remplacements ne reconfiguent pas les routes nginx groupées ni la liste d'autorisation du serveur d'autorisation et ne doivent pas être utilisés indépendamment dans le déploiement hébergé.

L'instance de recherche exige une authentification pour chaque requête (y compris tools/list) et rejette les jetons OAuth dont l'audience ne correspond pas à sa propre ressource.

Exemples de configuration

Pour l'utilisation de l'API cloud :

export FIRECRAWL_API_KEY=your-api-key

Pour une instance auto-hébergée :

# 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

Utilisation avec Claude Desktop

Ajoutez ceci à votre claude_desktop_config.json :

{
  "mcpServers": {
    "mcp-server-firecrawl": {
      "command": "npx",
      "args": ["-y", "firecrawl-mcp"],
      "env": {
        "FIRECRAWL_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

Comment Choisir un Outil

Utilisez ce guide pour sélectionner l'outil adapté à votre tâche :

• Si vous connaissez l'URL exacte souhaitée : utilisez scrape (avec le format JSON pour les données structurées)
• Si vous avez plusieurs URLs connues : appelez scrape pour chaque URL. Si vous avez spécifiquement besoin d'une opération API groupée, utilisez l'endpoint batch de l'API Firecrawl en dehors de MCP.
• Si vous devez découvrir des URLs sur un site : utilisez map
• Si vous souhaitez rechercher des informations sur le web : utilisez search
• Si vous avez une question de programmation (une bibliothèque, un contrat API, un message d'erreur, un bug connu) : utilisez developer search
• Si vous avez besoin d'articles scientifiques (littérature biomédicale, sciences de la vie, clinique ou arXiv) : utilisez les outils de recherche — ils recherchent dans les résumés et le texte intégral des articles. search avec categories: ["research"] est une chose différente : un filtre de site sur des résultats web ordinaires.
• Si vous avez besoin d'une recherche multi-sources qui renvoie des données structurées, ne connaissez pas les URLs, ou la réponse couvre plusieurs sites (une entité plus ses champs, une liste, un ensemble de données) : utilisez agent
• Si vous souhaitez analyser un site entier ou une section : utilisez crawl (avec des limites !)
• Si vous avez besoin d'automatisation de navigateur interactive (clic, saisie, navigation) : utilisez interact avec une URL pour une nouvelle page, ou scrape + interact lorsque vous avez déjà scrapé la page ou avez besoin d'un contrôle de scrape plus précis

Tableau de référence rapide

Outil	Idéal pour	Renvoie
scrape	Contenu d'une seule page	JSON (préféré) ou markdown
interact	Interagir avec une URL ou une page scrapée	Résultat d'exécution + scrapeId pour le mode URL
map	Découvrir des URLs sur un site	URL[]
crawl	Extraction multi-pages (avec limites)	statut/données finales du crawl après sondage interne
parse	Fichiers et références d'upload hébergées	markdown, JSON ou sortie document
search	Recherche web d'informations	results[]
developer	Questions de programmation sur des sources développeur	results[] avec passages
agent	Recherche multi-sources, sites inconnus ou nombreux	JSON (données structurées)
monitor	Vérifications récurrentes de pages	métadonnées de monitor/vérification et diffs
research	Recherche d'articles et de dépôts GitHub	résultats de recherche et correspondances de dépôts

Guide de sélection du format

Lors de l'utilisation de scrape, choisissez le bon format :

• Format JSON (recommandé pour la plupart des cas) : Utilisez-le lorsque vous avez besoin de données spécifiques d'une page. Définissez un schéma en fonction de ce que vous devez extraire. Cela maintient les réponses concises et évite le dépassement de la fenêtre de contexte.
• Format Markdown (à utiliser avec parcimonie) : Uniquement lorsque vous avez réellement besoin du contenu complet de la page, comme pour lire un article entier en vue de le résumer ou pour analyser la structure de la page.

Outils disponibles

1. Outil Scrape (firecrawl_scrape)

Extrayez le contenu d'une seule URL avec des options avancées.

Idéal pour :

• L'extraction de contenu d'une seule page, lorsque vous savez exactement quelle page contient l'information.

Déconseillé pour :

• L'extraction de contenu de plusieurs pages (utilisez des appels scrape répétés pour des URL connues, ou map + scrape pour découvrir les URL d'abord, ou crawl pour le contenu complet de la page)
• Lorsque vous n'êtes pas sûr de la page contenant l'information (utilisez search)

Erreurs courantes :

• Passer une liste d'URL à un seul appel scrape. Appelez scrape une fois par URL dans MCP. Si vous avez spécifiquement besoin d'une opération API groupée, utilisez le point de terminaison batch de l'API Firecrawl en dehors de MCP.
• Utiliser le format markdown par défaut (utilisez le format JSON pour extraire uniquement ce dont vous avez besoin).

Choisir le bon format :

• Format JSON (préféré) : Pour la plupart des cas d'utilisation, utilisez le format JSON avec un schéma pour extraire uniquement les données spécifiques nécessaires. Cela maintient les réponses ciblées et évite le dépassement de la fenêtre de contexte.
• Format Markdown : Uniquement lorsque la tâche nécessite réellement le contenu complet de la page (par exemple, résumer un article entier, analyser la structure de la page).

Exemple d'invite :

« Obtenez les détails du produit à partir de https://example.com/product. »

Exemple d'utilisation (format JSON - préféré) :

{
  "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"]
        }
      }
    ]
  }
}

Exemple d'utilisation (format markdown - lorsque le contenu complet est nécessaire) :

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

Exemple d'utilisation (format branding - extraire l'identité de marque) :

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

Format branding : Extrait l'identité complète de la marque (couleurs, polices, typographie, espacement, logo, composants d'interface utilisateur) pour l'analyse de conception ou la réplication de style. Confidentialité : Définissez redactPII: true pour renvoyer le contenu avec les informations personnelles identifiables expurgées.

Renvoie :

• Données structurées JSON, markdown, profil de marque ou autres formats spécifiés.

2. Outil Map (firecrawl_map)

Cartographiez un site Web pour découvrir toutes les URL indexées sur le site.

Idéal pour :

• Découvrir les URL d'un site Web avant de décider quoi scraper
• Trouver des sections spécifiques d'un site Web

Déconseillé pour :

• Lorsque vous savez déjà quelle URL spécifique vous avez besoin (utilisez scrape)
• Lorsque vous avez besoin du contenu des pages (utilisez scrape après la cartographie)

Erreurs courantes :

• Utiliser crawl pour découvrir les URL au lieu de map

Exemple d'invite :

« Listez toutes les URL sur example.com. »

Exemple d'utilisation :

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

Renvoie :

• Tableau d'URL trouvées sur le site

3. Outil Search (firecrawl_search)

Recherchez sur le Web et extrayez éventuellement le contenu des résultats de recherche.

Idéal pour :

• Trouver des informations spécifiques sur plusieurs sites Web, lorsque vous ne savez pas quel site Web contient l'information.
• Lorsque vous avez besoin du contenu le plus pertinent pour une requête

Déconseillé pour :

• Lorsque vous savez déjà quel site Web scraper (utilisez scrape)
• Lorsque vous avez besoin d'une couverture complète d'un seul site Web (utilisez map ou crawl)

Erreurs courantes :

• Utiliser crawl ou map pour des questions ouvertes (utilisez search à la place)

Exemple d'utilisation :

{
  "name": "firecrawl_search",
  "arguments": {
    "query": "remote work stipend policies at tech companies",
    "highlights": true,
    "limit": 5,
    "lang": "en",
    "country": "us",
    "scrapeOptions": {
      "formats": ["markdown"],
      "onlyMainContent": true,
      "redactPII": true
    }
  }
}

Définissez highlights sur true pour demander des extraits pertinents à la requête ou false pour conserver les extraits de recherche d'origine. Omettez-le pour utiliser le comportement par défaut de l'API.

Pour les articles scientifiques, voir Outils de recherche : ils recherchent dans les résumés et le texte intégral des articles, tandis que categories: ["research"] ici filtre les résultats Web ordinaires vers les sites Web affiliés à la recherche.

Renvoie :

• Tableau de résultats de recherche (avec contenu extrait facultatif), plus un champ id. Passez ce id à firecrawl_search_feedback après avoir utilisé les résultats pour rembourser 1 crédit (la recherche coûte 2) et améliorer la qualité de la recherche.

Exemple d'invite :

« Comparez les politiques d'indemnité de travail à distance dans les entreprises technologiques. »

3b. Outil de retour de recherche (firecrawl_search_feedback)

Envoie un retour structuré sur un résultat firecrawl_search précédent. Le premier retour par identifiant de recherche rembourse 1 crédit et améliore la qualité de recherche de Firecrawl. Idempotent par identifiant de recherche.

Appelez ceci après chaque recherche que vous utilisez réellement (ou qui n'a pas aidé). Un retour mauvais/partiel avec missingContent est tout aussi précieux qu'un bon retour.

Désinscription : définissez FIRECRAWL_NO_SEARCH_FEEDBACK=1 (ou FIRECRAWL_DISABLE_SEARCH_FEEDBACK=1) dans l'environnement au démarrage du serveur MCP. L'outil firecrawl_search_feedback ne sera pas enregistré, donc les agents ne peuvent pas l'appeler. Les administrateurs d'équipe peuvent également désactiver le retour côté serveur ; dans ce cas, l'outil est enregistré mais renvoie toujours feedbackErrorCode: "TEAM_OPTED_OUT".

Champ le plus important : missingContent. C'est un tableau de contenus spécifiques que l'agent s'attendait à trouver mais n'a pas trouvés. Une entrée par sujet manquant — celles-ci s'agrègent entre les équipes et nous indiquent quoi indexer ensuite.

Plafond de remboursement quotidien (par équipe, par jour UTC, 100 crédits par défaut). Une fois que le creditsRefundedToday d'une équipe atteint dailyRefundCap, les soumissions ultérieures enregistrent toujours le retour mais ne remboursent plus de crédits. La réponse définit dailyCapReached: true. Les agents doivent cesser d'appeler cet outil pour le reste de la journée UTC lorsqu'ils voient cet indicateur.

Exemple d'utilisation :

{
  "name": "firecrawl_search_feedback",
  "arguments": {
    "searchId": "0193f6c5-1234-7890-abcd-1234567890ab",
    "rating": "good",
    "valuableSources": [
      {
        "url": "https://docs.firecrawl.dev/features/search",
        "reason": "Most up-to-date description of /search."
      }
    ],
    "missingContent": [
      {
        "topic": "Pricing for the search endpoint",
        "description": "No pricing tier table for /search specifically."
      },
      { "topic": "Per-team rate limits" }
    ],
    "querySuggestions": "Boost docs.firecrawl.dev for queries that mention 'firecrawl'"
  }
}

Renvoie :

• JSON { success, feedbackId, creditsRefunded, alreadySubmitted? }.

3c. Outil de retour générique (firecrawl_feedback)

Envoie un retour structuré pour un travail de point de terminaison v2 terminé via /v2/feedback. Utilisez ceci pour un retour au niveau du point de terminaison sur les travaux scrape, parse, map ou search. Pour la qualité des résultats de recherche spécifiquement, préférez firecrawl_search_feedback car il inclut des conseils spécifiques à la recherche.

Gardez le retour concis : utilisez des codes de problème, des balises, des notes courtes, des URL, des numéros de page et de petits objets de métadonnées. N'incluez pas les sorties brutes de scrape/parse.

Désinscription : définissez FIRECRAWL_NO_ENDPOINT_FEEDBACK=1 (ou FIRECRAWL_DISABLE_ENDPOINT_FEEDBACK=1) dans l'environnement au démarrage du serveur MCP. L'outil firecrawl_feedback ne sera pas enregistré, donc les agents ne peuvent pas l'appeler.

Exemple d'utilisation :

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

Renvoie :

• JSON { success, feedbackId, creditsRefunded, creditsRefundedToday?, dailyRefundCap?, dailyCapReached?, alreadySubmitted?, warning? }.

4. Outil Crawl (firecrawl_crawl)

Démarre un travail de crawl, interroge jusqu'à ce qu'il atteigne un état terminal et renvoie l'état/les données finaux du crawl.

Idéal pour :

• L'extraction de contenu de plusieurs pages liées, lorsque vous avez besoin d'une couverture complète.

Déconseillé pour :

• L'extraction de contenu d'une seule page (utilisez scrape)
• Lorsque les limites de jetons sont une préoccupation (utilisez map + scrape pour un contrôle plus strict)
• Lorsque vous avez besoin de résultats rapides (le crawl peut être lent)

Avertissement : Les réponses de crawl peuvent être très volumineuses et peuvent dépasser les limites de jetons. Limitez la profondeur du crawl et le nombre de pages, ou utilisez map + scrape pour un contrôle plus strict.

Erreurs courantes :

• Définir limit ou maxDiscoveryDepth trop élevé (provoque un dépassement de jetons)
• Utiliser crawl pour une seule page (utilisez scrape à la place)

Exemple d'invite :

« Obtenez tous les articles de blog des deux premiers niveaux de example.com/blog. »

Exemple d'utilisation :

{
  "name": "firecrawl_crawl",
  "arguments": {
    "url": "https://example.com/blog/*",
    "maxDiscoveryDepth": 2,
    "limit": 100,
    "allowExternalLinks": false,
    "deduplicateSimilarURLs": true
  }
}

Renvoie :

• État et données finaux du crawl après interrogation interne, y compris id, status, completed, total, creditsUsed, expiresAt, next et data. Utilisez le id renvoyé avec firecrawl_check_crawl_status si vous devez revérifier le travail plus tard.

5. Vérifier l'état du crawl (firecrawl_check_crawl_status)

Vérifiez l'état et les résultats d'un travail de crawl existant par ID.

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

Renvoie :

• La réponse inclut l'état du travail de crawl :

6. Outil Parse (firecrawl_parse)

Analysez des fichiers locaux ou des références de téléversement hébergées avec le point de terminaison /v2/parse de Firecrawl.

Idéal pour : PDF, documents Word, feuilles de calcul, fichiers HTML et autres documents nécessitant une sortie markdown ou JSON structurée. Le MCP hébergé prend en charge un flux de référence de téléversement en deux étapes ; les lectures directes de fichiers locaux nécessitent un FIRECRAWL_API_URL auto-hébergé.

Déconseillé pour : URL distantes (utilisez scrape), plusieurs fichiers en un seul appel (appelez parse une fois par fichier) ou actions uniquement navigateur telles que les captures d'écran et les clics.

Flux MCP hébergé : Le MCP hébergé ne peut pas lire directement le système de fichiers de l'appelant. Appelez firecrawl_parse avec filePath pour recevoir une commande de téléversement à courte durée de vie et nextToolCall, téléversez le fichier localement, puis appelez firecrawl_parse à nouveau avec le uploadRef renvoyé. La création de l'URL de téléversement hébergée nécessite l'authentification Firecrawl ou l'éligibilité sans clé. En mode npx firecrawl-mcp local, l'analyse directe de fichiers nécessite actuellement FIRECRAWL_API_URL pointant vers une API Firecrawl auto-hébergée ; un serveur local simple avec uniquement une clé API cloud ne peut pas lire et téléverser des fichiers via cet outil.

Exemple d'utilisation :

{
  "name": "firecrawl_parse",
  "arguments": {
    "filePath": "/absolute/path/to/document.pdf",
    "formats": ["markdown"],
    "parsers": ["pdf"],
    "zeroDataRetention": true
  }
}

Renvoie : Contenu du document analysé ou instructions de téléversement hébergées avec un nextToolCall.

7. Données structurées avec Scrape JSON

Pour des données structurées d'une page connue, appelez firecrawl_scrape une fois par URL avec formats: ["json"]. Mettez l'invite d'extraction et le schéma JSON dans 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"]
      }
    }
  }
}

Lorsque les URL ne sont pas connues ou que les données s'étendent sur plusieurs sites, utilisez firecrawl_agent pour la recherche multi-sources.

8. Outil Agent (firecrawl_agent)

Agent de recherche Web autonome qui renvoie des données structurées lorsque vous ne connaissez pas les URL ou que la réponse s'étend sur plusieurs sites. Décrivez les champs dont vous avez besoin, passez éventuellement un schéma JSON et des URL de départ, et l'agent recherche, navigue, lit les pages et renvoie du JSON assemblé à partir de plusieurs sources. Utilisez-le pour une entité plus ses champs, pour des listes et des ensembles de données, et pour des pages nécessitant une navigation pour atteindre les données. Pour une URL connue, utilisez firecrawl_scrape avec le format JSON à la place.

Comment cela fonctionne :

L'agent effectue des recherches Web, suit des liens, lit des pages et collecte des données de manière autonome. Cela s'exécute de manière asynchrone - il renvoie immédiatement un ID de travail, et vous interrogez firecrawl_agent_status pour vérifier quand c'est terminé et récupérer les résultats.

Flux de travail asynchrone :

1. Appelez firecrawl_agent avec votre invite/schéma → renvoie un ID de travail
2. Faites d'autre travail pendant que l'agent recherche (peut prendre des minutes pour des requêtes complexes)
3. Interrogez firecrawl_agent_status avec l'ID de travail pour vérifier la progression
4. Lorsque l'état est « terminé », la réponse inclut les données extraites

Idéal pour :

• Tâches de recherche complexes où vous ne connaissez pas les URL exactes
• Collecte de données multi-sources
• Trouver des informations dispersées sur le Web
• Tâches où vous pouvez faire d'autre travail en attendant les résultats

Déconseillé pour :

• Le scraping simple d'une seule page où vous connaissez l'URL (utilisez scrape avec le format JSON - plus rapide et moins cher)

Arguments :

• prompt : Description en langage naturel des données souhaitées (obligatoire, max 10 000 caractères)
• urls : Tableau facultatif d'URL pour concentrer l'agent sur des pages spécifiques
• schema : Schéma JSON facultatif pour la sortie structurée

Exemple d'invite :

« Trouvez les fondateurs de Firecrawl et leurs parcours »

Exemple d'utilisation (démarrer l'agent, puis interroger pour les résultats) :

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

Puis interrogez avec firecrawl_agent_status en utilisant l'ID de travail renvoyé.

Exemple d'utilisation (avec URL - l'agent se concentre sur des pages spécifiques) :

{
  "name": "firecrawl_agent",
  "arguments": {
    "urls": ["https://docs.firecrawl.dev", "https://firecrawl.dev/pricing"],
    "prompt": "Compare the features and pricing information from these pages"
  }
}

Renvoie :

• ID de travail pour la vérification de l'état. Utilisez firecrawl_agent_status pour interroger les résultats.

9. Vérifier l'état de l'agent (firecrawl_agent_status)

Vérifiez l'état d'un travail d'agent et récupérez les résultats lorsqu'il est terminé. Utilisez ceci pour interroger les résultats après avoir démarré un agent.

Modèle d'interrogation : La recherche d'agent peut prendre des minutes pour des requêtes complexes. Interrogez ce point de terminaison périodiquement (par exemple, toutes les 10 à 30 secondes) jusqu'à ce que l'état soit « terminé » ou « échoué ».

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

États possibles :

• processing : L'agent recherche toujours - revenez plus tard
• completed : Recherche terminée - la réponse inclut les données extraites
• failed : Une erreur s'est produite

10. Outil Interact (firecrawl_interact)

Interagissez avec une nouvelle URL ou avec une page déjà ouverte par firecrawl_scrape. Idéal pour : Cliquer, taper, naviguer et extraire l'état de pages dynamiques sans restaurer les outils de navigateur obsolètes.

Options d'utilisation :

• Passez url pour extraire et ouvrir une page en vue d'une interaction en un seul appel MCP.
• Passez scrapeId pour continuer à interagir avec une page déjà extraite.
• Passez exactement un de url ou scrapeId, plus soit prompt soit code.

Exemple d'utilisation :

{
  "name": "firecrawl_interact",
  "arguments": {
    "url": "https://example.com",
    "prompt": "Click the pricing link and summarize the visible plans"
  }
}

Renvoie : Le résultat de l'interaction et, en mode URL, le scrapeId dérivé pour le suivi ou le nettoyage.

11. Outil d'arrêt d'interaction (firecrawl_interact_stop)

Arrête une session d'interaction pour une page extraite lorsque vous avez terminé d'interagir.

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

12. Outils de recherche (firecrawl_research_*)

Recherchez et inspectez des articles et des dépôts GitHub via les outils MCP de recherche.

Couverture : Résumés d'articles et texte intégral dans la littérature biomédicale, sciences de la vie et clinique (PubMed, bioRxiv, medRxiv) ainsi que arXiv et d'autres sources scientifiques.

Outils de recherche disponibles :

• firecrawl_research_search_papers : rechercher les métadonnées et résumés d'articles avec une requête en langage naturel, avec filtres facultatifs par auteur, catégorie et date.
• firecrawl_research_inspect_paper : récupérer les métadonnées canoniques pour un identifiant d'article (arXiv, PMC, PMID ou DOI).
• firecrawl_research_related_papers : étendre à partir d'un ou plusieurs articles d'ancrage via le graphe de citations.
• firecrawl_research_read_paper : lire des passages en texte intégral d'un article spécifique.

Idéal pour : Les flux de travail de revue de littérature, de recherche d'articles et de découverte de dépôts où l'agent a besoin d'une surface de recherche ciblée plutôt que d'un scraping web général.

firecrawl_search avec categories: ["research"] est une surface différente : il filtre les résultats web ordinaires vers des sites affiliés à la recherche et renvoie des extraits de pages, pas des enregistrements d'articles. Utilisez ces outils lorsque la question porte sur la littérature elle-même, et passez plusieurs formulations distinctes de la même question — ils font remonter des articles différents d'une seule requête.

13. Outils de surveillance (firecrawl_monitor_*)

Créez et gérez des surveillances de pages récurrentes. Les surveillances exécutent des extractions ou des explorations planifiées, comparent chaque résultat à la dernière capture conservée, et peuvent notifier par webhook ou par e-mail.

Idéal pour :

• Surveiller une page ou quelques pages dans le temps
• Alerter sur des changements significatifs en utilisant un objectif en anglais simple
• Suivre l'historique des vérifications et les différences au niveau des pages

Modèle de création recommandé :

Utilisez page ou pages plus goal. Le serveur MCP construit la demande de surveillance avec un planning de 30 minutes et l'API active automatiquement le jugement des changements significatifs.

Le jugement des changements significatifs s'exécute automatiquement lorsque goal est défini. Les webhooks de page exposent isMeaningful et judgment sur les événements monitor.page.

Rédigez les objectifs comme des instructions de surveillance concises de 2 à 3 phrases. Dites ce qui doit déclencher une alerte, préservez toute portée donnée par l'utilisateur, et incluez des exclusions spécifiques à l'intention uniquement lorsque cela est évident d'après la demande. Le bruit générique tel que les espaces blancs, les modifications de formatage uniquement, les identifiants de requête, les paramètres de suivi, les métadonnées génériques et le chrome de page non lié est déjà géré par le juge, donc ne le répétez pas dans chaque objectif. Si l'utilisateur est vague, gardez l'objectif large ; s'il demande une surveillance large ou « tout changement », préservez cela. Si l'utilisateur dit qu'il ne se soucie pas de quelque chose, incluez-le explicitement.

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

Plusieurs pages avec 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"
  }
}

Demandes de création avancées :

Passez body lorsque vous avez besoin de cibles d'exploration, de suivi des changements JSON, de conservation personnalisée ou de contrôle explicite 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" }]
    }
  }
}

Autres outils de surveillance :

• firecrawl_monitor_list : lister les surveillances.
• firecrawl_monitor_get : obtenir une surveillance.
• firecrawl_monitor_update : mettre à jour des champs, y compris goal, judgeEnabled, webhook et notification.
• firecrawl_monitor_run : déclencher une vérification maintenant.
• firecrawl_monitor_delete : supprimer une surveillance (destructif ; n'appeler que lorsque l'utilisateur a l'intention de la retirer).
• firecrawl_monitor_checks : lister les vérifications, éventuellement filtrées par statut.
• firecrawl_monitor_check : obtenir les résultats au niveau de la page, y compris diff, snapshot, judgment.meaningful et judgment.meaningfulChanges.

14. Outil de recherche développeur (firecrawl_developer_search)

Recherchez dans un index conçu pour les agents de codage. L'index couvre les issues GitHub, les pull requests fusionnées, les README de dépôts et les sites de documentation organisés.

Idéal pour : Une question de programmation — comportement de code, bibliothèque ou framework, contrat d'API, message d'erreur ou bug connu.

Arguments :

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

• query (obligatoire) : la question ou l'expression de recherche développeur.
• k : nombre de résultats classés. La valeur par défaut est 10 et le maximum est 100.
• skills : définir sur "only" pour rechercher uniquement les fichiers de compétences d'agent.

Renvoie : Des résultats classés. Chaque résultat porte un identifiant, un type de source (issue, pull_request, readme ou doc), une URL, un titre et les passages correspondants en markdown.

firecrawl_search avec categories: ["developer"] recherche le même index à côté des résultats web. Utilisez plutôt cet outil lorsque vous voulez les passages correspondants, le filtre skills ou aucun résultat web dans la réponse. Le point de terminaison de recherche seule expose les deux outils, et le même choix s'applique là-bas.

Système de journalisation

Le serveur inclut une journalisation complète :

• Statut et progression des opérations
• Métriques de performance
• Suivi des limites de débit
• Conditions d'erreur

Exemples de messages de journal :

[INFO] Firecrawl MCP Server initialized successfully
[INFO] Starting scrape for URL: https://example.com
[ERROR] Rate limit exceeded

Gestion des erreurs

Le serveur fournit une gestion robuste des erreurs :

• Erreurs de limite de débit API remontées au client MCP
• Messages d'erreur détaillés
• Résilience réseau

Exemple de réponse d'erreur :

{
  "content": [
    {
      "type": "text",
      "text": "Error: Rate limit exceeded"
    }
  ],
  "isError": true
}

Développement

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

Contribution

1. Forkez le dépôt
2. Créez votre branche de fonctionnalité
3. Exécutez les tests : npm test
4. Soumettez une pull request

Remerciements aux contributeurs

Merci à @vrknetha, @cawstudios pour l'implémentation initiale !

Merci à MCP.so et Klavis AI pour l'hébergement et à @gstarwd, @xiangkaiz et @zihaolin96 pour l'intégration de notre serveur.

Licence

Licence MIT — voir le fichier LICENSE pour plus de détails