Firecrawl

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 en 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 URL 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 voulez aussi que le contenu des pages soit récupéré dans le même appel (le point de terminaison de recherche seule ne récupère jamais de 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 de navigateur ouverte sur plusieurs de vos propres étapes avec votre propre logique de nouvelle tentative et de terminaison : chaque appel firecrawl_interact exécute un tour prompt ou code jusqu'à son terme et rend le contrôle — 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 depuis le 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, non exécuté en mode local sans clé). La définition de 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 : le point de terminaison hébergé sans clé (https://mcp.firecrawl.dev/v2/mcp, sans clé API) n'expose que 3 — firecrawl_scrape, firecrawl_search, firecrawl_parse — et le point de terminaison de recherche seule dédié (https://mcp.firecrawl.dev/v2/mcp-search) expose un ensemble fixe de 6 outils en lecture seule.

Installation

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

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

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

Sur le tier 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 chaque fois que 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 point de terminaison MCP, pas une page de navigateur ; utilisez le flux de connexion de compte du client et n'ajoutez pas une deuxième 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 une conversation 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.

Point de terminaison de recherche seule

Une surface en lecture seule, de recherche seule, 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 ; le point de terminaison complet ci-dessus est inchangé. Consultez 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 la version 0.45.6+ de Cursor 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, puis 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 HTTP Streamable

Pour exécuter le serveur en utilisant HTTP Streamable 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}"
        }
      }
    }
  }
}

Vous pouvez éventuellement 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) : point de terminaison 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 d'identification 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 point de terminaison de jeton, et non transmis à l'API de scrape/recherche.

Surface de recherche seule (hébergée)

En mode hébergé (CLOUD_SERVICE=true), une deuxième instance dans le processus sert le point de terminaison de 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 nécessite 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 le bon outil pour 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 URL connues : appelez scrape pour chaque URL. 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.
• Si vous devez découvrir des URL 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 d'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 web sur des résultats web ordinaires.
• Si vous avez besoin d'une recherche multi-sources qui renvoie des données structurées, que vous ne connaissez pas les URL, ou que la réponse s'étend sur 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 URL sur un site	URL[]
crawl	Extraction multi-pages (avec limites)	statut/données de crawl final après interrogation interne
parse	Fichiers et références de téléversement hébergées	markdown, JSON ou sortie document
search	Recherche web d'informations	résultats[]
developer	Questions de programmation sur des sources développeur	résultats[] 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 et diffs de monitor/check
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) : À utiliser 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 des 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 d'un résumé ou 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.

Non recommandé 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 des 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 de prompt :

« Obtenez les détails du produit depuis 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 une identité de marque complète (couleurs, polices, typographie, espacement, logo, composants UI) pour l'analyse de conception ou la réplication de style. Confidentialité : Définissez redactPII: true pour renvoyer un contenu avec les informations personnelles identifiables expurgées.

Retourne :

• Données structurées JSON, markdown, profil de marque, ou d'autres formats selon les spécifications.

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

Non recommandé 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 des URL au lieu de map

Exemple de prompt :

« Listez toutes les URL sur example.com. »

Exemple d'utilisation :

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

Retourne :

• Tableau des 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 contient l'information.
• Lorsque vous avez besoin du contenu le plus pertinent pour une requête

Non recommandé pour :

• Lorsque vous savez déjà quel site 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 points saillants 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 affiliés à la recherche.

Retourne :

• Tableau de résultats de recherche (avec contenu extrait en option), 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 de prompt :

« Comparez les politiques d'allocation 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 retourne 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 — ils s'agrègent entre les équipes et nous indiquent quoi indexer ensuite.

Plafond de remboursement quotidien (par équipe, par jour UTC, défaut 100 crédits). Une fois que le creditsRefundedToday d'une équipe atteint dailyRefundCap, les soumissions suivantes 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 ce drapeau.

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

Retourne :

• 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 d'erreur, des balises, des notes courtes, des URL, des numéros de page et de petits objets de métadonnées. N'incluez pas de 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"
    }
  }
}

Retourne :

• 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 retourne le statut/données final du crawl.

Idéal pour :

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

Non recommandé 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 de prompt :

« 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
  }
}

Retourne :

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

5. Vérifier le statut du crawl (firecrawl_check_crawl_status)

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

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

Retourne :

• La réponse inclut le statut 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 téléversement-référence en deux étapes ; les lectures directes de fichiers locaux nécessitent un FIRECRAWL_API_URL auto-hébergé.

Non recommandé pour : URL distantes (utilisez scrape), plusieurs fichiers dans un seul appel (appelez parse une fois par fichier), ou actions uniquement navigateur telles que captures d'écran et 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 et nextToolCall, téléversez le fichier localement, puis appelez firecrawl_parse à nouveau avec le uploadRef retourné. La création de l'URL de téléversement hébergée nécessite une authentification Firecrawl ou une é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 clé API cloud uniquement 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
  }
}

Retourne : 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 le prompt 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 une recherche multi-sources.

8. Outil Agent (firecrawl_agent)

Agent de recherche web autonome qui retourne 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 retourne 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 unique, 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 retourne 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 asynchrone :

1. Appelez firecrawl_agent avec votre prompt/schéma → retourne un ID de travail
2. Faites autre chose 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 le statut 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 autre chose en attendant les résultats

Non recommandé pour :

• 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 que vous voulez (obligatoire, maximum 10 000 caractères)
• urls : Tableau facultatif d'URL pour concentrer l'agent sur des pages spécifiques
• schema : Schéma JSON facultatif pour une sortie structurée

Exemple de prompt :

« 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 retourné.

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

Retourne :

• ID de travail pour la vérification du statut. Utilisez firecrawl_agent_status pour interroger les résultats.

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

Vérifiez le statut 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 de l'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 le statut soit « terminé » ou « échoué ».

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

Statuts possibles :

• processing : L'agent recherche encore - vérifiez 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êtez 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.

Couvre : Les résumés d'articles et le texte intégral de la littérature biomédicale, en 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 les résumés d'articles avec une requête en langage naturel, avec des 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 de référence 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 revues de littérature, la recherche d'articles et les flux de travail 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 — elles font apparaître 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 au fil du temps
• Alerter sur des changements significatifs à l'aide d'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 calendrier 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 lorsqu'elles sont évidentes à partir de la demande. Le bruit générique tel que les espaces blancs, les changements de formatage uniquement, les identifiants de requête, les paramètres de suivi, les métadonnées génériques et l'habillage de page non pertinent 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 ; à appeler uniquement lorsque l'utilisateur a l'intention de la supprimer).
• 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 problèmes GitHub, les demandes de tirage fusionnées, les README de dépôts et les sites de documentation sélectionné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 la phrase 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 cet outil à la place 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 signalé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 demande de tirage

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