Firecrawl MCP

Firecrawl MCP Server

Ein Model Context Protocol (MCP)-Server, der Firecrawl, die Context-API für KI-Agenten, für MCP-kompatible Clients verfügbar macht: Suchen, Scrapen und Interagieren mit dem Live-Web und sauberes Markdown oder strukturierte Daten zurückerhalten.

Vielen Dank an @vrknetha und @knacklabs für die erste Implementierung!

Funktionen

• Das Web durchsuchen, optional mit vollständigem Seiteninhalt für jedes Ergebnis
• Suchindizes für Entwicklerquellen (GitHub-Issues, gemergte Pull Requests, READMEs und Docs), US-Regierungsquellen und wissenschaftliche Paper (PubMed, bioRxiv, medRxiv, arXiv) durchsuchen
• Jede URL in sauberes Markdown oder strukturiertes JSON scrapen
• PDFs und Dokumente parsen
• Eine Website crawlen, um Inhalte von vielen Seiten zu erhalten, oder sie mappen, um ihre URLs zu entdecken
• Mit Seiten in einem echten Browser interagieren: klicken, tippen, Formulare ausfüllen und durch dynamische Seiten navigieren
• Agent-Jobs für Recherchen aus mehreren Quellen ausführen, die strukturierte Daten zurückgeben
• Seiten überwachen und benachrichtigt werden, wenn sich ihr Inhalt ändert
• Aktuelle und historische Firecrawl-Credit-Nutzung prüfen
• Automatische Wiederholungsversuche und Rate Limiting
• Unterstützung für Cloud und Self-Hosting
• SSE-Unterstützung

Probieren Sie unseren MCP Server im Playground von MCP.so oder bei Klavis AI aus.

Wann Sie diesen Server verwenden sollten

• Verwenden Sie firecrawl_scrape, wenn Sie eine bekannte URL haben und deren Inhalt als Markdown oder als JSON gemäß einem von Ihnen bereitgestellten Schema wünschen.
• Verwenden Sie firecrawl_map, wenn Sie URLs auf einer Website entdecken möchten, ohne deren Inhalt abzurufen.
• Verwenden Sie firecrawl_crawl, wenn Sie Inhalte von vielen Seiten einer Website benötigen; legen Sie limit, includePaths/excludePaths oder maxDiscoveryDepth fest, um dies zu begrenzen.
• Verwenden Sie firecrawl_search, wenn Sie von einer Suchanfrage statt von einer URL ausgehen und rangierte Web-Ergebnisse wünschen. Ergebnisse enthalten Auszüge; rufen Sie vollständige Seiten mit firecrawl_scrape für die URLs ab, die Sie benötigen. scrapeOptions ruft die Seite jedes Ergebnisses im selben Aufruf ab und rechnet jede als Scrape ab, daher sollten Sie es für den Volltext einiger weniger Ergebnisse einsetzen (der reine Such-Endpunkt ruft niemals Inhalte ab).
• Verwenden Sie firecrawl_interact, wenn eine Seite einen Klick-, Tipp- oder Navigationsschritt erfordert, bevor Sie sie lesen können: Übergeben Sie ein url für eine frische Seite oder ein scrapeId, um auf einer bereits gescrapten Seite fortzufahren.
• Verwenden Sie die firecrawl_monitor_*-Tools, wenn dieselbe Seite nach einem wiederkehrenden Zeitplan mit Diffs und Änderungsbenachrichtigungen geprüft werden soll, statt sie einmalig abzurufen.
• Verwenden Sie firecrawl_credit_usage, um verbleibende Credits oder die Credit-Ausgaben nach Monat oder Tag zu prüfen, optional aufgeschlüsselt nach Endpunkt oder API-Schlüssel.
• Ziehen Sie etwas anderes in Betracht, wenn Sie eine Browser-Sitzung über viele eigene Schritte hinweg offen halten müssen, mit eigener Wiederholungs- und Abbruchlogik: Jeder firecrawl_interact-Aufruf führt einen prompt- oder code-Durchlauf bis zum Abschluss aus und gibt die Kontrolle zurück. Die Sitzung kann über scrapeId hinweg bestehen bleiben und endet mit firecrawl_interact_stop, aber Sie können sie innerhalb eines einzelnen Aufrufs nicht clientseitig interaktiv Schritt für Schritt steuern.

Dieser Server listet 27 Tools auf, wenn das vollständige Profil mit Standardeinstellungen registriert wird (Feedback-Tools eingeschlossen, nicht im lokalen Keyless-Modus laufend). Das Setzen von FIRECRAWL_NO_SEARCH_FEEDBACK=1 und/oder FIRECRAWL_NO_ENDPOINT_FEEDBACK=1 entfernt die entsprechenden Feedback-Tools und reduziert diese Anzahl, ebenso wie ein lokaler Keyless-Start. Für Clients mit einem Tool-Slot-Limit: Der gehostete Keyless-Endpunkt (https://mcp.firecrawl.dev/v2/mcp, ohne API-Schlüssel) stellt nur 3 bereit (firecrawl_scrape, firecrawl_search, firecrawl_parse), und der dedizierte reine Such-Endpunkt (https://mcp.firecrawl.dev/v2/mcp-search) stellt einen festen Satz von 9 Tools bereit (Suche, Entwickler-, Regierungs- und Recherche-Suche sowie Alexandria-Katalogsuche und -Ausführung).

Installation

Gehostetes MCP (Keyless-Free-Tier)

Verbinden Sie sich ohne Einrichtung mit dem remote gehosteten Server:

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

Im Keyless-Free-Tier funktionieren scrape, search und parse ohne API-Schlüssel (rate-limitiert). Andere Tools wie crawl, map und agent benötigen weiterhin einen Schlüssel.

Bevorzugen Sie OAuth oder einen API-Schlüssel, wann immer sich die Person anmelden kann. Das schaltet den vollständigen Toolsatz und höhere Limits frei.

Für eine interaktive Kontoverbindung konfigurieren Sie Ihren MCP-Client so, dass er diese Server-URL verwendet. Dies ist ein MCP-Endpunkt, keine Browserseite; verwenden Sie den Konto-Verbindungsablauf des Clients und fügen Sie beim erneuten Verbinden keinen zweiten Firecrawl-Server-Eintrag hinzu:

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

Für eine API-Schlüssel-Verbindung (zum Beispiel eine unbeaufsichtigte Integration) behalten Sie die Server-URL bei als:

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

Konfigurieren Sie dann den sicheren Header oder die Secret-Einstellung des Clients mit:

Authorization: Bearer <FIRECRAWL_API_KEY>

Geben Sie niemals einen API-Schlüssel in die Server-URL ein. Geben Sie niemals einen API-Schlüssel in einen Agenten-Chat ein. Konfigurieren Sie ihn direkt im Client oder im Secret-Manager. Siehe die Anleitung zur Einrichtung des gehosteten MCP und die Anleitung zum Agenten-Onboarding für client-spezifische Anweisungen.

Benennen Ihrer Integration

Eine Integration, die sich über HTTP verbindet, kann sich mit einem X-Firecrawl-Origin-Header selbst benennen, zum Beispiel X-Firecrawl-Origin: my-agent. Der Server meldet ihn an Firecrawl als Request-Origin mcp-my-agent@<server version>, anstelle des Client-Namens oder User-Agents, den er sonst melden würde. Verwenden Sie Buchstaben, Ziffern und Bindestriche: Jede Folge anderer Zeichen wird zu einem Bindestrich, führende und abschließende Bindestriche werden entfernt, und der Name wird bei 48 Zeichen abgeschnitten. Tool-Ergebnisse sind nicht betroffen; nur der an die Firecrawl-API gesendete Origin (und der an den beforeKeylessRequest eines Embedders übergebene) ändert sich.

Reiner Such-Endpunkt

Eine Suchoberfläche mit festem Umfang wird ebenfalls gehostet unter:

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

Sie stellt einen festen Satz von neun Tools bereit: firecrawl_search, firecrawl_developer_search, firecrawl_gov_search, die vier firecrawl_research_*-Tools und die beiden Alexandria-Tools firecrawl_find_tools und firecrawl_scrape. Ihr firecrawl_search ruft keinen Seiteninhalt ab.

Ausführen mit npx

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

Manuelle Installation

npm install -g firecrawl-mcp

Ausführen in Cursor

Cursor konfigurieren 🖥️ Hinweis: Erfordert Cursor Version 0.45.6+ Die aktuellsten Konfigurationsanweisungen finden Sie in der offiziellen Cursor-Dokumentation zur Konfiguration von MCP-Servern: Cursor MCP Server Configuration Guide

So konfigurieren Sie Firecrawl MCP in Cursor v0.48.6

1. Öffnen Sie die Cursor-Einstellungen
2. Gehen Sie zu Features > MCP Servers
3. Klicken Sie auf "+ Add new global MCP server"
4. Geben Sie den folgenden Code ein:

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

So konfigurieren Sie Firecrawl MCP in Cursor v0.45.6

1. Öffnen Sie die Cursor-Einstellungen
2. Gehen Sie zu Features > MCP Servers
3. Klicken Sie auf "+ Add New MCP Server"
4. Geben Sie Folgendes ein:
   • Name: "firecrawl-mcp" (oder Ihr bevorzugter Name)
   • Type: "command"
   • Command: env FIRECRAWL_API_KEY=your-api-key npx -y firecrawl-mcp

Wenn Sie Windows verwenden und auf Probleme stoßen, versuchen Sie cmd /c "set FIRECRAWL_API_KEY=your-api-key && npx -y firecrawl-mcp"

Ersetzen Sie your-api-key durch Ihren Firecrawl-API-Schlüssel. Falls Sie noch keinen haben, können Sie ein Konto erstellen und ihn unter https://www.firecrawl.dev/app/api-keys abrufen.

Nach dem Hinzufügen aktualisieren Sie die MCP-Serverliste, um die neuen Tools zu sehen. Der Composer Agent verwendet Firecrawl MCP automatisch, wenn es passend ist, aber Sie können es explizit anfordern, indem Sie beschreiben, was Sie aus dem Web benötigen. Rufen Sie den Composer mit Command+L (Mac) auf, wählen Sie "Agent" neben der Absenden-Schaltfläche und geben Sie Ihre Anfrage ein.

Ausführen in Windsurf

Fügen Sie dies zu Ihrer ./codeium/windsurf/model_config.json hinzu:

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

Ausführen im lokalen Streamable-HTTP-Modus

So führen Sie den Server lokal mit Streamable HTTP statt mit dem standardmäßigen stdio-Transport aus:

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

Verwenden Sie die URL: http://localhost:3000/mcp

In diesem Modus beantwortet der Server nur Anfragen, die an localhost, 127.0.0.1 oder [::1] (auf einem beliebigen Port) adressiert sind, sowie an die Adresse in HOST, wenn diese nicht 0.0.0.0 oder :: ist. Eine Anfrage, deren Host-Header einen anderen Host nennt oder deren Origin-Header eine andere Site nennt, erhält 403, und CORS-Header geben einen erlaubten Origin statt * zurück. GET- und HEAD-Anfragen an /health werden unabhängig vom Host beantwortet, damit Health-Checks weiter funktionieren, und der Server protokolliert für jede abgelehnte Anfrage eine Zeile mit FIRECRAWL_MCP_ALLOWED_HOSTS. Dies verhindert, dass von Ihnen besuchte Webseiten den lokalen Server über DNS-Rebinding oder Cross-Origin-Anfragen aufrufen und dessen FIRECRAWL_API_KEY nutzen.

Um den Server unter einem anderen Namen oder einer anderen Adresse zu erreichen, etwa einem Hostnamen hinter einem Reverse-Proxy oder einer LAN-IP, listen Sie ihn in FIRECRAWL_MCP_ALLOWED_HOSTS auf (kommagetrennt; Ports werden ignoriert). Dieselbe Liste entscheidet, welche Browser-Origins den Server aufrufen dürfen. Ein Reverse-Proxy auf derselben Maschine kann die standardmäßige Bind-Adresse beibehalten:

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

Clients auf anderen Maschinen benötigen außerdem, dass der Server auf einer Nicht-Loopback-Adresse lauscht, also setzen Sie zusätzlich HOST. Jeder Client, der den Port erreichen kann, wird dann mit dem FIRECRAWL_API_KEY des Servers bedient, daher tun Sie dies nur in einem Netzwerk, dem Sie vertrauen:

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

FIRECRAWL_MCP_ALLOWED_HOSTS=* schaltet die Prüfung ab und stellt den Wildcard-CORS-Header wieder her. Tun Sie das nur, wenn etwas vor dem Server Hosts und Origins selbst prüft.

Ausführen mit Docker

Das ghcr.io/firecrawl/firecrawl-mcp-server-Image führt denselben Server aus wie npx -y firecrawl-mcp. Jeder Build aus main wird mit latest, v<package version> und sha-<commit sha> getaggt. v<package version> verweist auf den neuesten Build dieser Version, daher pinnen Sie sha-<commit sha> (oder einen Digest), wenn Sie ein festes Image benötigen.

stdio (der Standard) für MCP-Clients, die den Server als Befehl starten:

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

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

Streamable HTTP, bereitgestellt unter http://localhost:3000/mcp:

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

Das Image setzt HOST=0.0.0.0 und PORT=3000; überschreiben Sie PORT (und die -p-Zuordnung), um anderswo zu lauschen. Der Server verwendet das FIRECRAWL_API_KEY des Containers für Anfragen, die keine eigenen Anmeldedaten senden, daher veröffentlicht das Beispiel den Port nur auf 127.0.0.1; machen Sie ihn nicht breiter zugänglich, es sei denn, Clients müssen ihren eigenen Schlüssel mitbringen. Setzen Sie FIRECRAWL_API_URL, um eine selbst gehostete Firecrawl-API zu verwenden. Der Container läuft als unprivilegierter Benutzer node. Der Server antwortet nur auf localhost, 127.0.0.1 und [::1] in den Headern Host und Origin, daher funktioniert die -p 127.0.0.1:3000:3000-Zuordnung unverändert; um ihn unter einem anderen Namen zu erreichen, setzen Sie -e FIRECRAWL_MCP_ALLOWED_HOSTS=<host> (siehe Lokaler Streamable-HTTP-Modus).

Ausführen in VS Code

Für eine Ein-Klick-Installation klicken Sie auf eine der Installationsschaltflächen unten...

Für eine manuelle Installation fügen Sie den folgenden JSON-Block zu Ihrer User Settings (JSON)-Datei in VS Code hinzu. Sie können dies tun, indem Sie Ctrl + Shift + P drücken und Preferences: Open User Settings (JSON) eingeben.

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

Optional können Sie ihn zu einer Datei namens .vscode/mcp.json in Ihrem Workspace hinzufügen. Dadurch können Sie die Konfiguration mit anderen teilen:

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

Konfiguration

Umgebungsvariablen

Erforderlich für die Cloud-API

• FIRECRAWL_API_KEY: Ihr Firecrawl-API-Schlüssel
  • Erforderlich bei Verwendung der Cloud-API (Standard)
  • Optional bei Verwendung einer selbst gehosteten Instanz mit FIRECRAWL_API_URL
• FIRECRAWL_API_URL (Optional): Benutzerdefinierter API-Endpunkt für selbst gehostete Instanzen
  • Beispiel: https://firecrawl.your-domain.com
  • Wenn nicht angegeben, wird die Cloud-API verwendet (erfordert API-Schlüssel)
• FIRECRAWL_INTEGRATION (Optional): Integrations-Tag für Apps, die diesen Server starten, etwa eine Editor-Erweiterung
  • Wird als integration-Feld von scrape-, batch scrape-, crawl-, map-, search-, extract-, agent-, parse-, interact- und feedback-Anfragen gesendet
  • Verwenden Sie einen Wert, der mit _ beginnt, zum Beispiel _zed

Lokaler HTTP-Modus

• FIRECRAWL_MCP_ALLOWED_HOSTS (Optional): Zusätzliche Hostnamen oder Adressen, auf die der Server mit HTTP_STREAMABLE_SERVER=true oder SSE_LOCAL=true antwortet, durch Kommas getrennt
  • localhost, 127.0.0.1, [::1] und ein nicht-Wildcard-HOST sind immer erlaubt; Ports werden ignoriert
  • Anfragen, deren Host- oder Origin-Header einen anderen Host nennt, erhalten 403, außer GET- und HEAD-Anfragen an /health
  • * deaktiviert die Prüfung; wird nicht mit CLOUD_SERVICE=true verwendet, das jeden Host beantwortet

MCP OAuth (Bearer-Zugriffstoken)

Firecrawl stellt OAuth-Zugriffstoken (fco_…) über den Autorisierungsserver auf firecrawl.dev aus. Dieser MCP-Server leitet die jeweilige Anmeldeinformation, die er auflöst, als Authorization: Bearer … an die Firecrawl-API weiter.

• HTTP-Stream-Transporte (CLOUD_SERVICE=true, HTTP_STREAMABLE_SERVER=true oder SSE_LOCAL=true): Clients sollten Authorization: Bearer <fco_access_token> bei MCP-Anfragen senden. Ein OAuth-Bearer-Token hat Vorrang vor x-firecrawl-api-key / x-api-key, wenn beide vorhanden sind.
• stdio: Verwenden Sie FIRECRAWL_OAUTH_TOKEN für ein statisches Zugriffstoken oder verwenden Sie weiterhin FIRECRAWL_API_KEY für einen API-Schlüssel.

Verwenden Sie ausschließlich Zugriffstoken (fco_…). Refresh-Token (fcr_…) müssen am Token-Endpunkt eingetauscht werden und dürfen nicht an die Scrape-/Search-API übergeben werden.

CLOUD_SERVICE=true

CLOUD_SERVICE=true stellt die Tools über streamable HTTP auf PORT bereit (Standard 3000, gebunden an 0.0.0.0) mit strengeren Standardeinstellungen: Jede Anfrage muss eine Anmeldeinformation mitführen (einen API-Schlüssel oder ein OAuth-Zugriffstoken), Scrape ist schreibgeschützt (siehe das Scrape-Tool unten), und firecrawl_parse akzeptiert nur Uploads.

FASTMCP_ENDPOINT wählt die Tool-Oberfläche: /v2/mcp (Standard) für den vollständigen Toolsatz, /v2/mcp-oauth für die Konto-Oberfläche oder /v2/mcp-search für die reinen Such-Tools (dies erfordert außerdem FIRECRAWL_MCP_SEARCH_OAUTH_ONLY=true). Bei der vollständigen Oberfläche startet eine reine Such-Instanz zusätzlich auf Port 3001; setzen Sie FIRECRAWL_MCP_SEARCH_ENABLED=false, um dies zu deaktivieren.

Konfigurationsbeispiele

Für die Nutzung der Cloud-API:

export FIRECRAWL_API_KEY=your-api-key

Für eine selbst gehostete Instanz:

# 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

Verwendung mit Claude Desktop

Fügen Sie dies zu Ihrer claude_desktop_config.json hinzu:

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

So wählen Sie ein Tool aus

Verwenden Sie diese Anleitung, um das richtige Tool für Ihre Aufgabe auszuwählen:

• Wenn Sie die genaue URL kennen, die Sie möchten: Verwenden Sie scrape (mit JSON-Format für strukturierte Daten)
• Wenn Sie mehrere bekannte URLs haben: Rufen Sie scrape für jede URL auf. Wenn Sie gezielt eine einzelne Bulk-API-Operation benötigen, verwenden Sie den Batch-Endpunkt der Firecrawl-API außerhalb von MCP.
• Wenn Sie URLs auf einer Website entdecken möchten: Verwenden Sie map
• Wenn Sie das Web nach Informationen durchsuchen möchten: Verwenden Sie search
• Wenn Sie eine Programmierfrage haben (eine Bibliothek, ein API-Vertrag, eine Fehlermeldung, ein bekannter Bug): Verwenden Sie developer search
• Wenn Sie eine rechtliche oder regulatorische Frage haben (ein Gesetz, eine Verordnung, ein Regelwerk, eine Gerichtsentscheidung oder eine andere US-Regierungsveröffentlichung): Verwenden Sie den Firecrawl Government Index
• Wenn Sie wissenschaftliche Paper benötigen (biomedizinische, lebenswissenschaftliche, klinische oder arXiv-Literatur): Verwenden Sie die Research-Tools, die Paper-Abstracts und Volltexte durchsuchen. search mit categories: ["research"] ist etwas anderes: ein Website-Filter über gewöhnliche Web-Ergebnisse.
• Wenn Sie Multi-Source-Recherche benötigen, die strukturierte Daten zurückgibt, die URLs nicht kennen oder die Antwort mehrere Websites umfasst (eine Entität plus ihre Felder, eine Liste, ein Datensatz): Verwenden Sie agent
• Wenn Sie eine ganze Website oder einen Abschnitt analysieren möchten: Verwenden Sie crawl (mit Limits!)
• Wenn Sie interaktive Browser-Automatisierung benötigen (klicken, tippen, navigieren): Verwenden Sie interact mit einer URL für eine frische Seite oder scrape + interact, wenn Sie die Seite bereits gescrapt haben oder eine engere Scrape-Kontrolle benötigen
• Wenn Sie Daten von einem katalogisierten Anbieter benötigen (Alexandria): Suchen Sie mit sources: ["alexandria"], prüfen Sie den ausgewählten Vertrag mit find_tools und führen Sie ihn mit scrape alexandria aus

Schnellreferenztabelle

Tool	Am besten geeignet für	Gibt zurück
scrape	Inhalt einer einzelnen Seite	JSON (bevorzugt) oder Markdown
interact	Interaktion mit einer URL oder gescrapten Seite	Ausführungsergebnis + scrapeId für den URL-Modus
map	Entdecken von URLs auf einer Website	URL[]
crawl	Extraktion über mehrere Seiten (mit Limits)	finaler Crawl-Status/Daten nach internem Polling
parse	Dateien und gehostete Upload-Referenzen	Markdown, JSON oder Dokumentausgabe
search	Websuche nach Informationen	results[]
find_tools	Durchsuchen des Alexandria-Katalogs und URL-Lookup	Anbieter, Tool-Verträge und nextTool-Navigation
developer	Programmierfragen über Entwicklerquellen	results[] mit Passagen
gov	US-Primärrecht und regulatorisches Material	results[] mit Snippets
agent	Multi-Source-Recherche, unbekannte oder viele Websites	JSON (strukturierte Daten)
monitor	Wiederkehrende Seitenprüfungen	Monitor-/Check-Metadaten und Diffs
research	Recherche in Papern und GitHub-Repositories	Rechercheergebnisse und Repo-Treffer

Leitfaden zur Formatwahl

Bei der Verwendung von scrape wählen Sie das richtige Format:

• JSON-Format (empfohlen für die meisten Fälle): Verwenden Sie es, wenn Sie bestimmte Daten von einer Seite benötigen. Definieren Sie ein Schema basierend auf dem, was Sie extrahieren möchten. Dies hält Antworten klein und vermeidet ein Überlaufen des Kontextfensters.
• Markdown-Format (sparsam verwenden): Nur wenn Sie wirklich den vollständigen Seiteninhalt benötigen, etwa um einen ganzen Artikel zum Zusammenfassen zu lesen oder die Seitenstruktur zu analysieren.

Verfügbare Tools

1. Scrape-Tool (firecrawl_scrape)

Scrapen Sie Inhalte von einer einzelnen URL mit erweiterten Optionen.

Am besten geeignet für:

• Extraktion des Inhalts einer einzelnen Seite, wenn Sie genau wissen, welche Seite die Informationen enthält.

Nicht empfohlen für:

• Extraktion von Inhalten aus mehreren Seiten (verwenden Sie wiederholte Scrape-Aufrufe für bekannte URLs oder map + scrape, um URLs zuerst zu entdecken, oder crawl für den vollständigen Seiteninhalt)
• Wenn Sie nicht sicher sind, welche Seite die Informationen enthält (verwenden Sie search)

Häufige Fehler:

• Eine Liste von URLs an einen Scrape-Aufruf übergeben. Rufen Sie scrape in MCP einmal pro URL auf. Wenn Sie gezielt eine einzelne Bulk-API-Operation benötigen, verwenden Sie den Batch-Endpunkt der Firecrawl-API außerhalb von MCP.
• Standardmäßig das Markdown-Format verwenden (verwenden Sie das JSON-Format, um nur das zu extrahieren, was Sie benötigen).

Das richtige Format wählen:

• JSON-Format (bevorzugt): Verwenden Sie für die meisten Anwendungsfälle das JSON-Format mit einem Schema, um nur die spezifischen benötigten Daten zu extrahieren. Dies hält Antworten fokussiert und verhindert ein Überlaufen des Kontextfensters.
• Markdown-Format: Nur wenn die Aufgabe wirklich den vollständigen Seiteninhalt erfordert (z. B. Zusammenfassen eines ganzen Artikels, Analysieren der Seitenstruktur).

Prompt-Beispiel:

"Hole die Produktdetails von https://example.com/product."

Verwendungsbeispiel (JSON-Format – bevorzugt):

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

Verwendungsbeispiel (Markdown-Format – wenn vollständiger Inhalt benötigt wird):

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

Verwendungsbeispiel (Branding-Format – Markenidentität extrahieren):

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

Branding-Format: Extrahiert eine umfassende Markenidentität (Farben, Schriften, Typografie, Abstände, Logo, UI-Komponenten) für Designanalyse oder Stilreplikation. Datenschutz: Setzen Sie redactPII: true, um Inhalte mit redigierten personenbezogenen Daten zurückzugeben. Mit CLOUD_SERVICE=true: scrape ist schreibgeschützt. Es übernimmt keinen Browser-actions und kann keine Anbieterbedingungen akzeptieren. Ein benannter profile lädt gespeicherten Browser-Zustand, ohne Änderungen daran zu speichern, und firecrawl_search des vollständigen Endpunkts behandelt scrapeOptions.profile auf dieselbe Weise. Um Browser-Zustand in einem Profil zu speichern, öffnen Sie die Seite mit firecrawl_interact (siehe unten). Ein Organisationsadministrator akzeptiert Bedingungen im Dashboard.

Gibt zurück:

• JSON-strukturierte Daten, Markdown, Branding-Profil oder andere Formate wie angegeben.

2. Map-Tool (firecrawl_map)

Mappen Sie eine Website, um alle indexierten URLs auf der Website zu entdecken.

Am besten geeignet für:

• Entdecken von URLs auf einer Website, bevor Sie entscheiden, was gescrapt werden soll
• Finden bestimmter Abschnitte einer Website

Nicht empfohlen für:

• Wenn Sie bereits wissen, welche spezifische URL Sie benötigen (verwenden Sie scrape)
• Wenn Sie den Inhalt der Seiten benötigen (verwenden Sie scrape nach dem Mapping)

Häufige Fehler:

• Crawl zum Entdecken von URLs statt map verwenden

Prompt-Beispiel:

"Liste alle URLs auf example.com auf."

Verwendungsbeispiel:

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

Gibt zurück:

• Array der auf der Website gefundenen URLs

3. Search-Tool (firecrawl_search)

Durchsuchen Sie das Web und extrahieren Sie optional Inhalte aus Suchergebnissen.

Am besten geeignet für:

• Finden bestimmter Informationen über mehrere Websites hinweg, wenn Sie nicht wissen, welche Website die Informationen enthält.
• Wenn Sie die relevantesten Inhalte für eine Anfrage benötigen

Nicht empfohlen für:

• Wenn Sie bereits wissen, welche Website gescrapt werden soll (verwenden Sie scrape)
• Wenn Sie eine umfassende Abdeckung einer einzelnen Website benötigen (verwenden Sie map oder crawl)

Häufige Fehler:

• Crawl oder map für offene Fragen verwenden (verwenden Sie stattdessen search)

Verwendungsbeispiel:

{
  "name": "firecrawl_search",
  "arguments": {
    "query": "remote work stipend policies at tech companies",
    "highlights": true,
    "limit": 5,
    "lang": "en",
    "country": "us"
  }
}

Um den Volltext einiger Ergebnisse im selben Aufruf zu erhalten, fügen Sie "scrapeOptions": { "formats": ["markdown"], "onlyMainContent": true } hinzu. Jedes abgerufene Ergebnis wird als Scrape abgerechnet, daher verwenden Sie für die meisten Fragen die Auszüge und firecrawl_scrape nur die URLs, die Sie benötigen.

Setzen Sie highlights auf true, um anfragerelevante Highlights anzufordern, oder auf false, um die ursprünglichen Such-Snippets beizubehalten. Lassen Sie es weg, um das Standardverhalten der API zu verwenden.

Fügen Sie "sources": ["alexandria"] für semantische Tool-Entdeckung in data.tools hinzu, optional gemischt mit Web/News/Images. Eine Anfrage ist erforderlich. Verwenden Sie firecrawl_find_tools für kontextbezogenes Nachschlagen und progressive Offenlegung; siehe Alexandria Tools.

Für wissenschaftliche Paper siehe Research Tools: Sie durchsuchen Paper-Abstracts und Volltexte, während categories: ["research"] hier gewöhnliche Web-Ergebnisse auf forschungsnahe Websites filtert.

Gibt zurück:

• Suchergebnisse gruppiert nach Quelle (data.web, data.images, data.news), mit optional gescraptem Inhalt, plus einem id-Feld. Jedes Ergebnis trägt eine source und eine 1-indizierte position, nummeriert ab 1 innerhalb ihrer eigenen Gruppe – kopieren Sie das Paar direkt in firecrawl_search_feedback's valuableResults, anstatt Array-Elemente zu zählen. Übergeben Sie diese id an firecrawl_search_feedback, nachdem Sie die Ergebnisse verwendet haben, um 1 Credit zu erstatten (search kostet 2) und die Suchqualität zu verbessern.

Prompt-Beispiel:

"Vergleiche Remote-Work-Stipendienrichtlinien über Tech-Unternehmen hinweg."

3b. Search-Feedback-Tool (firecrawl_search_feedback)

Sendet strukturiertes Feedback zu einem vorherigen firecrawl_search-Ergebnis. Das erste Feedback pro Such-ID erstattet 1 Credit und verbessert die Suchqualität von Firecrawl. Idempotent pro Such-ID.

Rufen Sie dies nach jeder Suche auf, die Sie tatsächlich verwenden (oder die nicht geholfen hat). Schlechtes/teilweises Feedback mit missingContent ist genauso wertvoll wie gutes Feedback.

Opt-out: Setzen Sie FIRECRAWL_NO_SEARCH_FEEDBACK=1 (oder FIRECRAWL_DISABLE_SEARCH_FEEDBACK=1) in der Umgebung beim Start des MCP-Servers. Das Tool firecrawl_search_feedback wird dann nicht registriert, sodass Agenten es nicht aufrufen können. Team-Administratoren können Feedback auch serverseitig deaktivieren; in diesem Fall ist das Tool registriert, gibt aber immer feedbackErrorCode: "TEAM_OPTED_OUT" zurück. Wichtigstes Feld: missingContent. Es ist ein Array mit konkreten Inhalten, die der Agent erwartet, aber nicht gefunden hat. Ein Eintrag pro fehlendem Thema; diese werden teamübergreifend aggregiert und zeigen uns, was als Nächstes indexiert werden sollte. Für nützliche Ergebnisse verwende valuableResults mit dem Paar source/position, das auf jedem Ergebnis vermerkt ist – Ergebnisse werden gruppiert, und jede Gruppe wird unabhängig von 1 an nummeriert, daher sind beide erforderlich. Liste jedes nützliche Ergebnis auf (nicht aufgelistete Ergebnisse gelten als nicht nützlich), und reserviere valuableSources für nützliche URLs, die nicht unter den zurückgegebenen Ergebnissen waren.

Tägliches Rückerstattungslimit (pro Team, pro UTC-Tag, Standard 100 Credits). Sobald creditsRefundedToday eines Teams dailyRefundCap erreicht, werden weitere Einreichungen zwar weiterhin als Feedback erfasst, erstatten aber keine Credits mehr. Die Antwort setzt dailyCapReached: true. Agenten sollten aufhören, dieses Tool für den Rest des UTC-Tages aufzurufen, wenn sie dieses Flag sehen.

Anwendungsbeispiel:

{
  "name": "firecrawl_search_feedback",
  "arguments": {
    "searchId": "0193f6c5-1234-7890-abcd-1234567890ab",
    "rating": "good",
    "valuableResults": [
      { "source": "web", "position": 1 },
      { "source": "web", "position": 3 },
      { "source": "news", "position": 2, "reason": "Broke the pricing change." }
    ],
    "valuableSources": [
      {
        "url": "https://docs.firecrawl.dev/pricing",
        "reason": "Not in the results; found via a result's pricing link. Answered the question."
      }
    ],
    "missingContent": [
      {
        "topic": "Pricing for the search endpoint",
        "description": "No pricing tier table for /search specifically."
      },
      { "topic": "Per-team rate limits" }
    ],
    "querySuggestions": "Boost docs.firecrawl.dev for queries that mention 'firecrawl'"
  }
}

Gibt zurück:

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

3c. Generisches Feedback-Tool (firecrawl_feedback)

Sendet strukturiertes Feedback für einen abgeschlossenen v2-Endpoint-Job über /v2/feedback. Verwende dies für Feedback auf Endpoint-Ebene zu scrape, parse, map oder search-Jobs. Für die Qualität von Suchergebnissen speziell bevorzuge firecrawl_search_feedback, da es suchspezifische Hinweise enthält.

Halte Feedback knapp: Verwende Issue-Codes, Tags, kurze Notizen, URLs, Seitenzahlen und kleine Metadaten-Objekte. Füge keine rohen Scrape-/Parse-Ausgaben ein.

Opt-out: Setze FIRECRAWL_NO_ENDPOINT_FEEDBACK=1 (oder FIRECRAWL_DISABLE_ENDPOINT_FEEDBACK=1) in der Umgebung, wenn du den MCP-Server startest. Das Tool firecrawl_feedback wird dann nicht registriert, sodass Agenten es nicht aufrufen können.

Anwendungsbeispiel:

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

Gibt zurück:

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

4. Crawl-Tool (firecrawl_crawl)

Startet einen Crawl-Job, fragt ab, bis er einen Endzustand erreicht, und gibt den finalen Crawl-Status/die Daten zurück.

Am besten geeignet für:

• Das Extrahieren von Inhalten aus mehreren zusammenhängenden Seiten, wenn du eine umfassende Abdeckung benötigst.

Nicht empfohlen für:

• Das Extrahieren von Inhalten aus einer einzelnen Seite (verwende scrape)
• Wenn Token-Limits ein Problem darstellen (verwende map + scrape für engere Kontrolle)
• Wenn du schnelle Ergebnisse benötigst (Crawling kann langsam sein)

Warnung: Crawl-Antworten können sehr groß werden und Token-Limits überschreiten. Begrenze die Crawl-Tiefe und die Seitenanzahl oder verwende map + scrape für engere Kontrolle.

Häufige Fehler:

• limit oder maxDiscoveryDepth zu hoch setzen (verursacht Token-Überlauf)
• crawl für eine einzelne Seite verwenden (verwende stattdessen scrape)

Prompt-Beispiel:

"Hole alle Blogbeiträge aus den ersten beiden Ebenen von example.com/blog."

Anwendungsbeispiel:

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

Gibt zurück:

• Finalen Crawl-Status und Daten nach internem Polling, einschließlich id, status, completed, total, creditsUsed, expiresAt, next und data. Verwende die zurückgegebene id mit firecrawl_check_crawl_status, wenn du den Job später erneut prüfen musst.

5. Crawl-Status prüfen (firecrawl_check_crawl_status)

Prüft den Status und die Ergebnisse eines bestehenden Crawl-Jobs anhand der ID.

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

Gibt zurück:

• Die Antwort enthält den Status des Crawl-Jobs:

6. Parse-Tool (firecrawl_parse)

Parst lokale Dateien oder gehostete Upload-Referenzen mit dem /v2/parse-Endpoint von Firecrawl.

Am besten geeignet für: PDFs, Word-Dokumente, Tabellen, HTML-Dateien und andere Dokumente, die Markdown- oder strukturierte JSON-Ausgabe benötigen. Der gehostete Endpoint verwendet einen zweistufigen Upload-Ablauf; lokales direktes Dateilesen erfordert ein selbst gehostetes FIRECRAWL_API_URL.

Nicht empfohlen für: Remote-URLs (verwende scrape), mehrere Dateien in einem Aufruf (rufe parse einmal pro Datei auf) oder reine Browser-Aktionen wie Screenshots und Klicks.

Gehosteter Endpoint: Er kann nicht auf dein Dateisystem zugreifen. Rufe firecrawl_parse mit filePath auf, um einen kurzlebigen Upload-Befehl und nextToolCall zu erhalten, lade die Datei lokal hoch und rufe dann firecrawl_parse erneut mit der zurückgegebenen uploadRef auf. Der Upload-Schritt erfordert Firecrawl-Authentifizierung oder den schlüssellosen Tarif. Im lokalen npx firecrawl-mcp-Modus erfordert das direkte Datei-Parsen derzeit FIRECRAWL_API_URL, das auf eine selbst gehostete Firecrawl-API verweist; ein einfacher lokaler Server nur mit Cloud-API-Schlüssel kann über dieses Tool keine Dateien lesen und hochladen.

Anwendungsbeispiel:

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

Gibt zurück: Geparsten Dokumentinhalt oder Anweisungen für den gehosteten Upload mit einer nextToolCall.

7. Strukturierte Daten mit Scrape JSON

Für strukturierte Daten von einer bekannten Seite rufe firecrawl_scrape einmal pro URL mit formats: ["json"] auf. Lege den Extraktions-Prompt und das JSON-Schema in jsonOptions ab.

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

Wenn die URLs nicht bekannt sind oder die Daten sich über mehrere Sites erstrecken, verwende firecrawl_agent für Recherche aus mehreren Quellen.

8. Agent-Tool (firecrawl_agent)

Autonomer Web-Recherche-Agent, der strukturierte Daten zurückgibt, wenn du die URLs nicht kennst oder die Antwort sich über mehrere Sites erstreckt. Beschreibe die Felder, die du benötigst, übergib optional ein JSON-Schema und Seed-URLs, und der Agent sucht, navigiert, liest Seiten und gibt JSON zurück, das aus mehreren Quellen zusammengestellt wurde. Verwende es für eine Entität plus ihre Felder, für Listen und Datensätze sowie für Seiten, die Navigation erfordern, um an die Daten zu gelangen. Für eine bekannte URL verwende stattdessen firecrawl_scrape mit JSON-Format.

So funktioniert es:

Der Agent führt Websuchen durch, folgt Links, liest Seiten und sammelt Daten autonom. Dies läuft asynchron – er gibt sofort eine Job-ID zurück, und du fragst firecrawl_agent_status ab, um zu prüfen, wann er fertig ist, und die Ergebnisse abzurufen.

Asynchroner Ablauf:

1. Rufe firecrawl_agent mit deinem Prompt/Schema auf → gibt Job-ID zurück
2. Erledige andere Arbeit, während der Agent recherchiert (kann bei komplexen Anfragen Minuten dauern)
3. Frage firecrawl_agent_status mit der Job-ID ab, um den Fortschritt zu prüfen
4. Wenn der Status "completed" ist, enthält die Antwort die extrahierten Daten

Am besten geeignet für:

• Komplexe Rechercheaufgaben, bei denen du die genauen URLs nicht kennst
• Datenerfassung aus mehreren Quellen
• Das Finden von Informationen, die über das Web verstreut sind
• Aufgaben, bei denen du andere Arbeit erledigen kannst, während du auf Ergebnisse wartest

Nicht empfohlen für:

• Einfaches Scraping einer einzelnen Seite, bei dem du die URL kennst (verwende scrape mit JSON-Format – schneller und günstiger)

Argumente:

• prompt: Natürlichsprachliche Beschreibung der Daten, die du möchtest (erforderlich, max. 10.000 Zeichen)
• urls: Optionales Array von URLs, um den Agenten auf bestimmte Seiten zu fokussieren
• schema: Optionales JSON-Schema für strukturierte Ausgabe
• effort: Optional. "low", "medium" oder "high" Reasoning-Budget für die Agent-Aufgabe.
• maxCredits: Optionale positive Ganzzahl. Ausgabenlimit in Credits für diesen Lauf. Die API verwendet standardmäßig 2.500, wenn es weggelassen wird, und begrenzt eine kostenlose Anfrage auf 2.500.
• strictConstrainToURLs: Optionaler Boolean. Wenn true, besucht der Agent nur die URLs in urls.
• threadId: Optional. Setzt einen bestehenden Thread fort: die threadId aus einem früheren firecrawl_agent- oder firecrawl_agent_status-Ergebnis. Weglassen, um einen neuen Thread zu starten. Bei einer Folgefrage werden weggelassene Einstellungen für mode, urls, schema und exchange aus dem vorherigen Turn übernommen.
• mode: Optional. "extract" (Standard) gibt bei jedem Turn das vollständige strukturierte Ergebnis zurück. "chat" ermöglicht es einer Folgefrage, die keine neuen Daten anfordert, eine kurze Antwort in message zu erhalten, statt erneut ausgeführt zu werden; exchange.requireApproval benötigt dies.
• exchange: Optional. Alexandria-Provider-Einstellungen für diesen Turn, unverändert an POST /v2/agent weitergegeben:
  • enabled, toolkits (bis zu 5 Provider-Slugs), maxCalls (1 bis 30), requireApproval (kostenpflichtige Aufrufe beenden den Turn mit einem pendingApproval; erfordert mode: "chat" im selben Aufruf, auch bei einer Folgefrage)
  • onTermsRequired: Was zu tun ist, wenn ein Alexandria-Provider, den der Agent verwenden würde, Datenbedingungen benötigt, die dein Team nicht akzeptiert hat. Gesperrte Provider werden in keinem Modus aufgerufen. Wenn es bei einer Folgefrage weggelassen wird, bleibt der Wert des vorherigen Turns erhalten.
    • "skip" (Standard): Antwort nur mit akzeptierten Providern. exchange.skippedProviders im Statusergebnis listet die gesperrten Provider auf, die geholfen hätten.
    • "ask": Dasselbe, plus ein Bedingungen-pendingApproval und exchange.requiresAction mit der Genehmigungs-ID und den Provider-Anforderungen. Lies die Bedingungen mit terms/show; ein Organisationsadministrator akzeptiert sie im Firecrawl-Dashboard.
  • approve: { approvalId, callIds?, always? } beantwortet mit Ja das pendingApproval, mit dem der vorherige Turn endete. callIds und always gelten nur für Genehmigungen kostenpflichtiger Aufrufe.
  • decline: { approvalId } beantwortet mit Nein. Ein abgelehntes Bedingungen-Angebot hält diese Provider für den Rest des Threads heraus.
  • approve und decline benötigen threadId, und nur eines von beiden kann gesendet werden.

Provider-Bedingungen (Ask-Modus): Es gibt keinen Auto-Accept-Modus. Wenn ein Turn mit einem Bedingungen-Angebot endet, enthält das Statusergebnis pendingApproval (kind: "terms") und exchange.requiresAction mit der approvalId und den Provider-Anforderungen. Jeder terms/accept-Deskriptor in dieser API-Nutzlast ist über MCP nicht verfügbar. So verwendest du den Provider:

1. Zeige dem Benutzer die Bedingungen (terms/show bis firecrawl_scrape mit alexandria).
2. Weise einen Organisationsadministrator an, die Bedingungen unter der URL des Providers oder in den Datenquellen-Einstellungen zu akzeptieren. Eine Datenanfrage ist keine Einwilligung.
3. Warte, bis der Administrator die Akzeptanz im Dashboard bestätigt.
4. Setze denselben Thread fort: Rufe firecrawl_agent mit derselben threadId und exchange.approve: { "approvalId": "..." } auf. Dies setzt die Recherche fort und akzeptiert keine Bedingungen.

Wenn der Benutzer Nein sagt, rufe stattdessen firecrawl_agent mit derselben threadId und exchange.decline: { "approvalId": "..." } auf.

Prompt-Beispiel:

"Finde die Gründer von Firecrawl und ihren Hintergrund"

Anwendungsbeispiel (Agent starten, dann Ergebnisse abfragen):

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

Frage dann mit firecrawl_agent_status unter Verwendung der zurückgegebenen Job-ID ab.

Anwendungsbeispiel (mit URLs – Agent fokussiert sich auf bestimmte Seiten):

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

Anwendungsbeispiel (Folgefrage im selben Thread):

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

Anwendungsbeispiel (Thread fortsetzen, nachdem ein Administrator die Akzeptanz im Dashboard bestätigt hat):

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

Gibt zurück:

• Job-ID zur Statusprüfung, plus threadId und threadTurn. Verwende firecrawl_agent_status, um Ergebnisse abzufragen.

9. Agent-Status prüfen (firecrawl_agent_status)

Prüft den Status eines Agent-Jobs und ruft Ergebnisse ab, wenn er abgeschlossen ist. Verwende dies, um nach dem Start eines Agenten Ergebnisse abzufragen.

Polling-Muster: Agent-Recherche kann bei komplexen Anfragen Minuten dauern. Frage diesen Endpoint regelmäßig ab (z. B. alle 10–30 Sekunden), bis der Status "completed" oder "failed" ist.

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

Mögliche Status:

• processing: Agent recherchiert noch – schaue später wieder vorbei
• completed: Recherche abgeschlossen – die Antwort enthält die extrahierten Daten
• failed: Ein Fehler ist aufgetreten

10. Interact-Tool (firecrawl_interact)

Interagiere mit einer frischen URL oder mit einer Seite, die bereits durch firecrawl_scrape geöffnet wurde.

Am besten geeignet für: Klicken, Tippen, Navigieren und Extrahieren des Zustands aus dynamischen Seiten, ohne die veralteten Browser-Tools wiederherzustellen.

Nutzungsoptionen:

• Übergib url, um eine Seite in einem einzigen MCP-Aufruf zu scrapen und zur Interaktion zu öffnen.
• Übergib scrapeId, um die Interaktion mit einer bereits gescrapten Seite fortzusetzen.
• Um den Browser-Zustand (Cookies, localStorage) in einem benannten Profil zu speichern, übergib url mit scrapeOptions: { "profile": { "name": "my-profile", "saveChanges": true } }. Der Zustand wird gespeichert, wenn firecrawl_interact_stop die Sitzung beendet.
• Übergib genau eines von url oder scrapeId, plus entweder prompt oder code.

Anwendungsbeispiel:

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

Gibt zurück: Interaktionsergebnis und, im URL-Modus, die abgeleitete scrapeId für Folgeschritte oder Aufräumen.

11. Interact-Tool stoppen (firecrawl_interact_stop)

Beendet eine Interact-Sitzung für eine gescrapte Seite, wenn du mit der Interaktion fertig bist.

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

12. Recherche-Tools (firecrawl_research_*)

Durchsuche und inspiziere Paper und GitHub-Repositories mit den Research-MCP-Tools.

Umfasst: Paper-Abstracts und Volltexte aus biomedizinischer, lebenswissenschaftlicher und klinischer Literatur (PubMed, bioRxiv, medRxiv) sowie arXiv und andere wissenschaftliche Quellen.

Verfügbare Research-Tools:

• firecrawl_research_search_papers: Metadaten und Abstracts von Papers mit einer natürlichsprachlichen Anfrage durchsuchen, mit optionalen Filtern für Autor, Kategorie und Datum.
• firecrawl_research_inspect_paper: kanonische Metadaten für eine Paper-ID (arXiv, PMC, PMID oder DOI) abrufen.
• firecrawl_research_related_papers: von einem oder mehreren Anker-Papers über den Zitationsgraphen expandieren.
• firecrawl_research_read_paper: Volltextpassagen aus einem bestimmten Paper lesen.

Am besten geeignet für: Literaturrecherche, Paper-Lookup und Repository-Discovery-Workflows, bei denen der Agent eine fokussierte Research-Oberfläche statt einer allgemeinen Websuche benötigt.

firecrawl_search mit categories: ["research"] ist eine andere Oberfläche: Es filtert gewöhnliche Web-Ergebnisse auf forschungsnahe Websites und liefert Seiten-Snippets, keine Paper-Datensätze. Verwende diese Tools, wenn die Frage die Literatur selbst betrifft, und übergib mehrere unterschiedliche Formulierungen derselben Frage, da sie andere Papers zutage fördern als eine einzelne Anfrage.

13. Monitor-Tools (firecrawl_monitor_*)

Erstelle und verwalte wiederkehrende Seiten-Monitore. Monitore führen geplante Scrapes oder Crawls aus, vergleichen jedes Ergebnis mit dem letzten aufbewahrten Snapshot und können per Webhook oder E-Mail benachrichtigen.

Am besten geeignet für:

• Beobachten einer Seite oder einiger weniger Seiten über die Zeit
• Alarmieren bei bedeutsamen Änderungen anhand eines in einfacher Sprache formulierten Ziels
• Nachverfolgen des Prüfverlaufs und von Diffs auf Seitenebene

Empfohlenes Erstellungsmuster:

Verwende page oder pages plus goal. Der MCP-Server baut die Monitor-Anfrage mit einem 30-Minuten-Zeitplan, und die API aktiviert die Bewertung bedeutsamer Änderungen automatisch.

Die Bewertung bedeutsamer Änderungen läuft automatisch, wenn goal gesetzt ist. Seiten-Webhooks stellen isMeaningful und judgment bei monitor.page-Ereignissen bereit.

Formuliere Ziele als knappe Monitor-Anweisungen von 2-3 Sätzen. Sage, was einen Alarm auslösen soll, bewahre jeden vom Nutzer vorgegebenen Umfang und füge absichtsspezifische Ausschlüsse nur hinzu, wenn sie aus der Anfrage offensichtlich hervorgehen. Generisches Rauschen wie Leerraum, reine Formatierungsänderungen, Request-IDs, Tracking-Parameter, generische Metadaten und unbezogene Seiten-Elemente wird bereits vom Judge behandelt, wiederhole es also nicht in jedem Ziel. Wenn der Nutzer vage ist, halte das Ziel breit; wenn er eine breite Überwachung oder „jede Änderung" verlangt, bewahre das. Wenn der Nutzer sagt, dass ihn etwas nicht interessiert, schließe es ausdrücklich ein.

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

Mehrere Seiten mit 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"
  }
}

Erweiterte Erstellungsanfragen:

Übergib body, wenn du Crawl-Ziele, JSON-Änderungsverfolgung, benutzerdefinierte Aufbewahrung oder explizite judgeEnabled-Steuerung benötigst.

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

Weitere Monitor-Tools:

• firecrawl_monitor_list: Monitore auflisten.
• firecrawl_monitor_get: einen Monitor abrufen.
• firecrawl_monitor_update: Felder aktualisieren, einschließlich goal, judgeEnabled, webhook und notification.
• firecrawl_monitor_run: eine Prüfung sofort auslösen.
• firecrawl_monitor_delete: einen Monitor löschen (destruktiv; nur aufrufen, wenn der Nutzer ihn entfernen möchte).
• firecrawl_monitor_checks: Prüfungen auflisten, optional nach Status gefiltert.
• firecrawl_monitor_check: Ergebnisse auf Seitenebene abrufen, einschließlich diff, snapshot, judgment.meaningful und judgment.meaningfulChanges.

14. Developer-Search-Tool (firecrawl_developer_search)

Durchsuche einen Index, der für Coding-Agenten aufgebaut wurde. Der Index umfasst GitHub-Issues, gemergte Pull Requests, Repository-READMEs und Code-Dokumentation.

Am besten geeignet für: Eine Programmierfrage: Codeverhalten, eine Bibliothek oder ein Framework, ein API-Vertrag, eine Fehlermeldung oder ein bekannter Bug.

Argumente:

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

• query (erforderlich): die Entwicklerfrage oder Suchphrase.
• k: Anzahl der gerankten Ergebnisse. Der Standard ist 10 und das Maximum ist 100.
• skills: auf "only" setzen, um nur Agent-Skill-Dateien zu durchsuchen.

Gibt zurück: Gerankte Ergebnisse. Jedes Ergebnis trägt eine ID, einen Quelltyp (issue, pull_request, readme oder doc), eine URL, einen Titel und die übereinstimmenden Passagen in Markdown.

firecrawl_search mit categories: ["developer"] durchsucht denselben Index neben den Web-Ergebnissen. Verwende stattdessen dieses Tool, wenn du die übereinstimmenden Passagen, den skills-Filter oder keine Web-Ergebnisse in der Antwort möchtest. Der Search-only-Endpunkt stellt beide Tools bereit, und dieselbe Wahl gilt auch dort.

14b. Government-Index-Search-Tool (firecrawl_gov_search)

Durchsuche Primärrecht und regulatorisches Material aus US-amerikanischen föderalen, staatlichen und lokalen Regierungsquellen: Gesetze, Verordnungen, Codes, Gerichtsurteile und andere Regierungsveröffentlichungen.

Am besten geeignet für: Eine rechtliche oder regulatorische Frage, die den maßgeblichen Text oder eine offizielle Regierungsquelle benötigt.

Argumente:

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

• query (erforderlich): die rechtliche oder regulatorische Frage oder Suchphrase.
• k: Anzahl der gerankten Ergebnisse. Der Standard ist 10 und das Maximum ist 100.
• jurisdiction: nur Seiten einer Jurisdiktion behalten: "us" für föderal, oder "us-" plus einen zweistelligen Bundesstaats- oder Territoriumscode, wie "us-ca" oder "us-dc".
• court: nur Seiten behalten, die für ein Gericht gekennzeichnet sind, nach CourtListener-Gerichts-ID, wie "scotus", "ca9" oder "nysd".
• courtType: nur Seiten eines Gerichtstyps behalten: federal-supreme, federal-appellate, federal-district, federal-bankruptcy, federal-special, military, state-supreme, state-appellate, state-trial, state-special oder state-attorney-general.
• cites: nur Seiten behalten, die ein Gesetz oder einen Fall zitieren, als gedruckte Zitation wie "42 U.S.C. § 1983" oder "5 U.S. 137", oder eine Zitations-ID wie "us:usc:42:1983".
• domain: nur Seiten einer Website behalten, wie "irs.gov".

Die Filter sind optional und kombinieren sich: Ein Ergebnis muss jedem gesetzten Filter entsprechen. Filter behalten nur Seiten, die der Index gekennzeichnet hat, daher kann eine gefilterte Suche relevante Seiten auslassen, und keine Ergebnisse bedeuten nicht, dass keine existieren. Gerichtskennzeichnungen sind für föderale Gerichte und Fallrechtssammlungen am vollständigsten.

Gibt zurück: Gerankte Ergebnisse. Jedes Ergebnis trägt eine Position, einen Titel, eine URL und das übereinstimmende Snippet. Der Search-only-Endpunkt stellt auch dieses Tool bereit.

firecrawl_search mit categories: ["gov"] durchsucht dieselben Quellen und gibt die Treffer in data.web mit category: "gov" zurück. Die Kategorie gov akzeptiert diese Filter nicht und kann nicht mit anderen Kategorien kombiniert werden.

15. Alexandria-Tools

Firecrawl Alexandria ist ein Katalog von Datenanbietern, die über die Firecrawl-API mit einem Firecrawl-API-Schlüssel in einem Team mit Alexandria-Zugriff erreichbar sind. Schlüssellose Sitzungen (gehostet oder lokal) erhalten Alexandria requires an API key on a team with Alexandria access; Alexandria-Discovery-Tools werden für gehostete schlüssellose Sitzungen nicht aufgeführt.

Semantische Discovery (firecrawl_search):

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

data.tools liefert standardmäßig kompakte Vorschläge mit Anbieter, Fähigkeit und Beschreibung. Setze toolDetail: "summary" für Metadaten und Navigation, oder toolDetail: "full" für Verträge einschließlich Eingaben, Antwortfeldern und Beispielen. domainTools: true fügt kontextuelle Treffer zu Query-Erwähnungen und Ergebnis-URLs in demselben Array hinzu. Prüfe warning auf nicht verfügbare Discovery. Die Suche erfordert eine Query und akzeptiert keine Katalog-Traversierungsfilter. Diese Discovery funktioniert sowohl auf der vollständigen als auch auf der Search-only-MCP-Oberfläche.

Progressive Offenlegung (firecrawl_find_tools):

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

Beginne ohne Argumente für Kategorien und verenge dann schrittweise den Katalog:

Argumente	Ergebnis
{}	Kategorien und kurze Beschreibungen
{"categories":["podcasts"]}	Anbieter in dieser Kategorie
{"categories":["podcasts"],"providers":["particle"]}	Kompakte Tool-Namen und -Beschreibungen
{"providers":["particle"],"capabilities":["podcasts/episodes/search"]}	Vollständige ausgewählte Eingaben, Einschränkungen, Antwort und Beispiele

Kein Gruppen-Hop erforderlich. Explizites level unterstützt categories, providers, groups oder tools; explizites expand wählt Vertragsabschnitte. expand: [] hält Ergebnisse kompakt, auch wenn eine Fähigkeit ausgewählt wird. Für breite vollständige Verträge fordere explizit level: "tools" und expand: ["options", "response", "examples"] an. URLs ermöglichen kontextuelle Discovery ohne Abrufen der Seite. Tool-Ergebnisse lassen Credit-Preise pro Fähigkeit weg, sofern includeCosts: true nicht gesetzt ist; nachfolgende nextTool-Argumente behalten es bei.

Ergebnisse stehen in data.alexandria[0].data. Folge dem nextTool eines Elements, indem du sein name mit seinem arguments aufrufst; das nextTool der Seite treibt die Paginierung voran. Bestehende next-Objekte bleiben Alexandria-Discovery-Aufrufe, nutzbar über firecrawl_scrape. Discovery kostet null Credits und führt die Anbieter-Tools nie aus. Lies den ausgewählten vollständigen Vertrag vor der Ausführung.

Diese Steuerungen erfordern ein passendes Alexandria-API-Deployment.

Ausführen (firecrawl_scrape mit alexandria): übergib alexandria statt url (genau eines von beiden; requestId und timeout können ebenfalls angegeben werden). Ein einzelner Aufruf oder ein Array von bis zu zehn Aufrufen wird akzeptiert.

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

Gibt zurück: { success, scrape_id, requestId, data: { alexandria: [...], creditsCost } }. Jedes Element ist entweder ein Ergebnis (provider, capability, data, records, upstreamStatus) oder ein error mit einem code; der Batch schlägt wegen eines Anbieterfehlers nie als Ganzes fehl, und data.creditsCost ist der für die Anfrage insgesamt berechnete Betrag. Alexandria-Fehlerkörper (403 ohne Alexandria-Zugriff und 402/409-Abrechnungsstatus) werden in-band mit ihrem code weitergeleitet.

Die Ausführung erzeugt eine x-request-id und gibt sie bei Erfolg oder Fehler zurück. Wiederhole die identische Payload mit dieser requestId; erstelle nach einem unklaren Ausgang keine neue ID. Verfügbare Credits werden von der API geprüft.

Ein Alexandria-Anbieter, dessen Bedingungen das Team nicht akzeptiert hat, schlägt fehl, bevor etwas läuft, mit HTTP 403 und diesem Body:

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

Das Tool-Ergebnis leitet es als Fehler weiter, wobei structuredContent code, status: 403, requestId, das unveränderte requiresAction-Objekt und next_actions (human_action_required dann retry_same_request) trägt. Das Akzeptieren von Bedingungen ist ein rechtlicher Akt, daher akzeptiert sie ein Organisationsadministrator im Firecrawl-Dashboard, nicht über MCP. Verwende den zurückgegebenen nextTool-Aufruf, um die Vereinbarung über firecrawl_scrape mit alexandria: [{provider: "firecrawl", capability: "terms/show", options: {provider: "<provider>"}}] zu lesen, getrennt von der Anbieterausführung gesendet, und lege sie dem Nutzer vor. Ein Organisationsadministrator akzeptiert sie dann unter requiresAction.url, oder unter https://www.firecrawl.dev/app/settings?tab=data-sources. firecrawl_scrape lehnt jede andere terms/*-Fähigkeit ab, sodass es keine Kontenänderungen vornimmt. Eine Anfrage nach Daten ist keine Zustimmung, und es erfolgen keine automatische Akzeptanz oder unklare Wiederholungen. Für den blockierten Abruf werden keine Credits berechnet. Nachdem der Administrator die Akzeptanz bestätigt hat, rufe dasselbe Tool erneut mit der identischen Payload und requestId auf.

16. Credit-Usage-Tool

Das Tool erfordert ein authentifiziertes Firecrawl-Konto und ist schreibgeschützt.

• firecrawl_credit_usage ist standardmäßig { "view": "current" } und gibt remainingCredits, planCredits, billingPeriodStart und billingPeriodEnd zurück. Die verbleibenden Credits können die Plan-Credits übersteigen, wenn das Team Top-ups oder Zuschüsse hat.
• Übergeben Sie { "view": "historical" } für Kalendermonatszeiträume mit startDate, endDate und creditsUsed. Das Übergeben von { "byApiKey": true } wählt außerdem die historische Ansicht und teilt Zeiträume nach API-Schlüssel auf; jede Zeile enthält dann apiKey. Das Übergeben von { "byEndpoint": true } teilt Zeiträume stattdessen nach dem Endpunkt auf, der die Credits verbraucht hat (scrape, search, crawl, map, agent, ...); jede Zeile enthält dann endpoint. Übergeben Sie { "bin": "day" } für einen Zeitraum pro UTC-Tag statt pro Kalendermonat. Kombinieren Sie byApiKey nicht mit byEndpoint und keines davon mit { "view": "current" }. Der endDate des neuesten Zeitraums kann null sein. Wenn die Firecrawl-API die Endpunkt-Aufteilung oder tägliche Zeiträume noch nicht anbietet, enthält das Ergebnis ein notice und monatliche Werte.

Programmatische Nutzung (instabil)

Das Paket stellt außerdem einen Library-Einstiegspunkt bereit, um den Server in eine andere Laufzeitumgebung einzubetten. Er ist instabil: Die API, ihre Optionen und ihre Typen können sich in jeder Version ändern, einschließlich Minor- und Patch-Releases, daher sollten Sie eine exakte Version pinnen.

npm install --save-exact firecrawl-mcp zod

Das Beispiel definiert Tool-Parameter mit zod, daher installiert das einbettende Projekt es als eigene Abhängigkeit.

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

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

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

Setzen Sie host explizit. Ohne diese Einstellung lauscht der Server auf localhost, das Node an eine einzelne Adresse bindet (oft nur ::1), sodass Anfragen an 127.0.0.1 abgelehnt werden. Verwenden Sie 0.0.0.0 oder ::, um Verbindungen von anderen Maschinen nur hinter Netzwerkzugriffskontrollen oder einer unstable_hooks.authenticate-Prüfung anzunehmen: Ohne eine solche wird jeder Aufrufer, der den Port erreichen kann, mit dem konfigurierten apiKey bedient.

Die Library prüft Host oder Origin nicht, sofern nicht angefordert, und ihre CORS-Header erlauben jeden Ursprung. Ein Server, der von einem Browser auf derselben Maschine erreichbar ist, sollte httpStream.allowedHosts übergeben (zum Beispiel ['localhost', '127.0.0.1', '[::1]']): Anfragen, deren Host- oder Origin-Header einen anderen Host nennt, erhalten dann 403 (außer GET und HEAD auf dem Health-Pfad), und CORS-Header geben den erlaubten Ursprung zurück. Die Kommandozeile setzt diese Liste im lokalen HTTP-Modus.

Die Optionen spiegeln die Umgebungsvariablen der CLI wider: apiUrl, apiKey, transport, logging, safeMode, fileAccess (local oder upload), requireCredential, searchFeedback und endpointFeedback. unstable_hooks akzeptiert:

Hook	Zweck
authenticate(request)	Löst die Sitzung für eine Anfrage auf; wirft einen Response, um sie abzulehnen.
wrapTool(tool)	Dekoriert jedes registrierte Tool.
onToolResult(event)	Beobachtet den Start und das Ergebnis jedes Tool-Aufrufs.
instructions	Server-Anweisungen oder eine Funktion, die aus den Standardwerten auswählt.
registerExtraTools(registrar, context)	Fügt Tools nach den integrierten hinzu.
outboundRequest(session)	Anmeldedaten und zusätzliche Header für jede Firecrawl-API-Anfrage.
beforeKeylessRequest(session, origin)	Lehnt eine Anfrage ohne Schlüssel durch Werfen ab.
toolFilter(name)	Lässt integrierte Tools aus der Instanz weg.
configureHttp(app)	Fügt HTTP-Routen hinzu.
oauth.protectedResource	Stellt OAuth-Metadaten für geschützte Ressourcen bereit.

Der Server basiert auf dem offiziellen MCP TypeScript SDK (@modelcontextprotocol/server). Verwenden Sie die aus firecrawl-mcp/server exportierten Typen (Session, ToolDefinition, ToolRegistrar, FirecrawlMcpServerHooks und andere) statt der des SDK selbst.

Der Einstiegspunkt exportiert außerdem die Hilfsfunktionen, die die integrierten Tools verwenden, wie recoveryPayload, normalizeHeader, requestOrigin, isRuntimeUserAgent, initializeClientSlug, searchToolBaseFields, searchOutputSchema und structuredCompact, damit zusätzliche Tools und Hooks das Verhalten der integrierten Tools nachbilden können. Auch sie sind instabil.

Logging-System

Der Server enthält umfassendes Logging:

• Operationsstatus und Fortschritt
• Leistungsmetriken
• Verfolgung von Rate-Limits
• Fehlerbedingungen

Beispiel-Logmeldungen:

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

Fehlerbehandlung

Der Server bietet robuste Fehlerbehandlung:

• API-Rate-Limit-Fehler, die an den MCP-Client weitergegeben werden
• Detaillierte Fehlermeldungen
• Netzwerkresilienz

Beispiel-Fehlerantwort:

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

Entwicklung

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

Mitwirken

1. Forken Sie das Repository
2. Erstellen Sie Ihren Feature-Branch
3. Führen Sie Tests aus: npm test
4. Reichen Sie einen Pull Request ein

Danksagung an Mitwirkende

Danke an @vrknetha, @cawstudios für die erste Implementierung!

Danke an MCP.so und Klavis AI für das Hosting und an @gstarwd, @xiangkaiz und @zihaolin96 für die Integration unseres Servers.

Lizenz

MIT-Lizenz – siehe LICENSE-Datei für Details

Strukturierte Daten und große Ergebnisse

Die authentifizierte Suche verwendet standardmäßig Web-Ergebnisse, semantische Alexandria-Tools und Domain-Treffer. Beginnen Sie mit der eigentlichen Frage. Verwenden Sie firecrawl_find_tools für die direkte semantische Tool-Suche, ausgewählte Verträge oder progressives Durchsuchen: Kategorien → Anbieter → kompakte Tools → ausgewählter Vertrag. Führen Sie Tools über firecrawl_scrape aus; gewöhnliches URL-Scraping und die Suche führen niemals automatisch Anbieter-Tools aus.

Bevorzugen Sie für ausgewählte Verträge expand: ["options", "response"] und fordern Sie Beispiele nur an, wenn die Eingabeform unklar ist. Untersuchen Sie verwandte Fähigkeiten gemeinsam und verwenden Sie die zurückgegebenen Verträge erneut.

Für ein potenziell großes Workflow-Ergebnis geben Sie vor der Ausführung eine requestId auf oberster Ebene an und behalten Sie sie bei. Diese ID bleibt verfügbar, selbst wenn der Client die Antwort ablehnt. Reguläre URL-Scrapes verwenden stattdessen die zurückgegebene Scrape-ID.

Für ein großes aufbewahrtes Workflow- oder reguläres Scrape-Ergebnis rufen Sie firecrawl_scrape auf mit:

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

Lesen Sie stdout, stderr, exitCode und workspaceId in data.alexandria[0].data. Fahren Sie mit options: {workspaceId, command} fort, um response.json mit jq zu untersuchen, oder mit document.md unter Verwendung begrenzter Textbefehle für reguläre Scrapes. Halten Sie die Ausgabe selektiv. Das Laden von Quellen muss ein eigenständiger Aufruf sein; seine verschachtelte Quell-ID unterscheidet sich von der ID der Ausführungsanfrage auf oberster Ebene. Workspaces laufen nach fünf Minuten Inaktivität ab, und nicht jedes Ergebnis wird aufbewahrt (einschließlich ZDR- und API-Anbieter-Workflow-Payloads). Such-IDs werden nicht unterstützt.

Für Workflow-Quellen bewahrt response.json den API-Umschlag: Wählen Sie .data.alexandria[].data, dann den response.key des ausgewählten Vertrags, wenn dieser nicht leer ist. Kombinieren Sie verwandte Zählungen und Projektionen in einem Bash-Befehl, wenn diese Form bekannt ist, statt wiederholt Schlüssel zu untersuchen.

Erfolgreiche Alexandria-Ausführungsantworten über geschätzten 20.000 Tokens (serialisierte UTF-8-Bytes geteilt durch vier) geben eine kleine Übergabe zurück, nachdem das entfernte Bash bestätigt hat, dass der vollständige Batch zugänglich ist. Folgen Sie nextTool, um die aufbewahrten Daten zu untersuchen. Dies fügt einen Bash-Aufruf hinzu und startet einen Workspace mit einer Inaktivitäts-TTL von fünf Minuten. Die vollständige Payload bleibt erhalten. Wenn die Bestätigung fehlschlägt, bleibt die ursprüngliche Antwort inline. Suche, gewöhnliches URL-Scraping, Fehlerantworten und Firecrawl-Dienstaufrufe bleiben unverändert. Dieses Auslieferungsbudget misst nicht den verbleibenden Kontext des Clients; es wird kein prozesslokaler Ergebnis-Cache hinzugefügt. Wenn lokale Dateisystem-Tools verfügbar sind, ist das Speichern der CLI-Ausgabe und das Lesen ausgewählter Abschnitte eine weitere Option.

Die CLI-Erkennungssequenz entspricht diesen MCP-Aufrufen:

Absicht	Tool	Argumente
Web- + semantische + Domain-Tools	firecrawl_search	{"query":"<user question>"}
Nur semantische Tools	firecrawl_search	{"query":"<user question>","sources":["alexandria"]}
Kategorien	firecrawl_find_tools	{}
Anbieter in einer Kategorie	firecrawl_find_tools	{"categories":["<category-id>"]}
Kompakte Anbieter-Tools	firecrawl_find_tools	{"providers":["<provider-id>"]}
Ausgewählter Vertrag	firecrawl_find_tools	{"providers":["<provider-id>"],"capabilities":["<capability-id>"]}
Ausführen	firecrawl_scrape	{"alexandria":{"provider":"<provider-id>","capability":"<capability-id>","options":{"<required-field>":"<value>"}}}

Find Tools und die Ausführung sind sowohl auf der vollständigen Oberfläche als auch auf der Suchoberfläche verfügbar. Verwenden Sie einen vollständigen Vertrag aus der Suche erneut, wenn er vorhanden ist, statt einen weiteren Erkennungsaufruf zu machen. Folgen Sie der zurückgegebenen nextTool-Navigation nur, wenn weitere Ergebnisse benötigt werden.

Alexandria-Sitzungsfeedback

Das bestehende Tool firecrawl_feedback akzeptiert endpoint: "alexandria":

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

Das optionale objective ist das zugrunde liegende Ziel der Sitzung: was der Agent oder sein Benutzer letztlich erreichen wollte, über die einzelne Website in requestedWebsite hinaus.

Dies verwendet authentifiziertes POST /v2/feedback, ohne Job-ID. Es muss innerhalb von 20 Minuten nach der letzten Alexandria-Suche, -Erkennung oder -Ausführung des Teams eintreffen; späteres Feedback wird mit FEEDBACK_WINDOW_EXPIRED abgelehnt. Berechtigtes Feedback kann 1 Credit erstatten, vorbehaltlich täglicher Obergrenzen von 10 Credits pro Website und 100 Credits pro Team (UTC-Tag). Nach Erreichen einer der beiden Obergrenzen wird Feedback weiterhin aufgezeichnet, jedoch ohne Erstattung, und die Antwort setzt websiteCapReached oder dailyCapReached. Optionale Arrays providerFeedback und capabilityFeedback beschreiben Abdeckungslücken und Ausführungsprobleme; das Tool-Schema listet die unterstützten Problemwerte auf. Ein new_capability_request erfordert requestedFunctionality; missing_capability (der Anbieter existiert, aber die Fähigkeit fehlt) nicht. Bestehende Feedback-Opt-out- und Authentifizierungskontrollen gelten.

Berechtigte Alexandria-Ausführungs- und -Erkennungsergebnisse enthalten einen feedbackTool-Zeiger mit dem Tool-Namen und einem Skelett der Argumente. Der Zeiger wird für Firecrawl-interne Aufrufe wie bash und wenn firecrawl_feedback nicht registriert ist (FIRECRAWL_NO_ENDPOINT_FEEDBACK oder Start ohne Schlüssel) weggelassen.