SerpApi MCP

SerpApi MCP Server

Eine Implementierung eines Model Context Protocol (MCP)-Servers, die mit SerpApi für umfassende Suchmaschinenergebnisse und Datenextraktion integriert ist.

Funktionen

• Suche über mehrere Suchmaschinen: Google, Bing, Yahoo, DuckDuckGo, YouTube, eBay und mehr
• Suchmaschinenressourcen: Parameterschemas für einzelne Suchmaschinen sind über MCP-Ressourcen verfügbar (siehe Suchtool)
• Wetterdaten in Echtzeit: Standortbezogene Wetterdaten mit Vorhersagen über Suchanfragen
• Börsendaten: Unternehmensfinanzdaten und Marktdaten über die Suchintegration
• Dynamische Ergebnisverarbeitung: Erkennt und formatiert automatisch verschiedene Ergebnistypen
• Flexible Antwortmodi: Vollständige oder kompakte JSON-Antworten
• JSON-Antworten (Standard): Strukturiertes JSON-Format mit vollständigem oder kompaktem Modus
• Markdown-Antworten: Reduzieren den Tokenverbrauch durchschnittlich um 50 % und bei APIs mit komplexem, verschachteltem JSON um mehr als 90 %.
• Interaktive Benutzeroberfläche (MCP Apps): Optionale Tools search_table und search_dashboard, die Ergebnisse in unterstützten Hosts als interaktive Benutzeroberfläche darstellen
• Claude Desktop-Erweiterung: Lokale Installation mit einem Klick über ein MCP Bundle (.mcpb), siehe unten

Schnellstart

Der SerpApi MCP Server ist als gehosteter Dienst unter mcp.serpapi.com verfügbar. Für die Verbindung benötigen Sie einen API-Schlüssel. Sie finden Ihren API-Schlüssel in Ihrem SerpApi-Dashboard.

Sie können Claude Desktop für die Verwendung des gehosteten Servers konfigurieren:

{
  "mcpServers": {
    "serpapi": {
      "type": "http",
      "url": "https://mcp.serpapi.com/YOUR_SERPAPI_API_KEY/mcp"
    }
  }
}

Sie können den gehosteten Server auch zu diesen MCP-Clients hinzufügen:

OpenClaw

openclaw mcp add serpapi --url https://mcp.serpapi.com/YOUR_SERPAPI_API_KEY/mcp --transport streamable-http

Claude Code

claude mcp add --transport http serpapi https://mcp.serpapi.com/mcp --header "Authorization: Bearer YOUR_SERPAPI_API_KEY"

Hermes

hermes mcp add serpapi --url https://mcp.serpapi.com/YOUR_SERPAPI_API_KEY/mcp

Codex (liest den Schlüssel aus SERPAPI_API_KEY in Ihrer Shell)

codex mcp add serpapi --url https://mcp.serpapi.com/mcp --bearer-token-env-var SERPAPI_API_KEY

Selbst hosten

git clone https://github.com/serpapi/serpapi-mcp.git
cd serpapi-mcp
uv sync && uv run src/server.py

Claude Desktop konfigurieren:

{
  "mcpServers": {
    "serpapi": {
      "type": "http",
      "url": "http://localhost:8000/YOUR_SERPAPI_API_KEY/mcp"
    }
  }
}

API-Schlüssel abrufen: serpapi.com/manage-api-key

Claude Desktop-Erweiterung (MCP-Bundle)

Für eine lokale Installation mit einem Klick laden Sie das .mcpb-Bundle aus der neuesten Version herunter und öffnen Sie es mit Claude Desktop (oder ziehen Sie es auf Einstellungen → Erweiterungen). Claude Desktop fragt während der Installation nach Ihrem SerpApi-API-Schlüssel, speichert ihn als vertrauliche Einstellung und führt den Server lokal über stdio aus. Python und Abhängigkeiten werden zum Installationszeitpunkt mit uv bereitgestellt. Dasselbe Bundle funktioniert unter macOS, Windows und Linux.

Derselbe stdio-Einstiegspunkt funktioniert mit jedem lokalen MCP-Host, der Server als Unterprozess startet:

{
  "mcpServers": {
    "serpapi": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/serpapi-mcp", "--frozen", "--no-dev", "src/stdio.py"],
      "env": { "SERPAPI_API_KEY": "YOUR_SERPAPI_API_KEY" }
    }
  }
}

Authentifizierung

Es werden zwei Methoden unterstützt:

• Headerbasiert: Authorization: Bearer YOUR_API_KEY (empfohlen: Der Schlüssel erscheint weder in URLs noch in Protokollen)
• Pfadbasiert: /YOUR_API_KEY/mcp, für Clients, die keine Header setzen können

Beispiele:

# Header-based
curl "https://mcp.serpapi.com/mcp" -H "Authorization: Bearer your_key" -d '...'

# Path-based
curl "https://mcp.serpapi.com/your_key/mcp" -d '...'

Für die Verbindung, das Auflisten von Tools oder das Lesen von Ressourcen ist kein Schlüssel erforderlich. search und die App-Tools benötigen einen Schlüssel und geben ohne ihn einen Fehler zurück.

Suchtool

Der MCP-Server verfügt über ein zentrales Suchtool, das alle SerpApi-Suchmaschinen und Ergebnistypen unterstützt. Alle verfügbaren Parameter finden Sie in der SerpApi-API-Referenz. Parameterschemas für Suchmaschinen werden außerdem als MCP-Ressourcen bereitgestellt: serpapi://engines (Index) und serpapi://engines/<engine>. Clients, die Argumentvervollständigung unterstützen, können Suchmaschinennamenvorschläge für serpapi://engines/{engine_name} anfordern. Das Präfix google_f schlägt beispielsweise passende Suchmaschinenkennungen vor. Dabei wird der Ressourcen-URI-Parameter vervollständigt, nicht eine beliebige Suchanfrage.

Die verfügbaren Parameter hängen von der jeweiligen API-Suchmaschine ab. Einige Beispielparameter sind unten aufgeführt:

• params.q (erforderlich): Suchanfrage
• params.engine: Suchmaschine (Standard: "google_light")
• params.location: Geografischer Filter
• params.output: Antwortformat; für JSON weglassen (Standard) oder für Markdown auf "md" setzen
• mode: Antwortmodus; "compact" entfernt Metadaten aus JSON, während Markdown unverändert zurückgegeben wird
• ...weitere Parameter finden Sie in der SerpApi-API-Referenz

Beispiele:

{"name": "search", "arguments": {"params": {"q": "coffee shops", "location": "Austin, TX"}}}
{"name": "search", "arguments": {"params": {"q": "weather in London"}}}
{"name": "search", "arguments": {"params": {"q": "AAPL stock"}}}
{"name": "search", "arguments": {"params": {"q": "news"}, "mode": "compact"}}
{"name": "search", "arguments": {"params": {"q": "detailed search"}, "mode": "complete"}}
{"name": "search", "arguments": {"params": {"q": "news", "output": "md"}}}
{"name": "search", "arguments": {"params": {"engine": "amazon", "k": "mechanical keyboards", "amazon_domain": "amazon.com", "output": "md"}}}
{"name": "search", "arguments": {"params": {"engine": "google_scholar", "q": "retrieval augmented generation"}}}
{"name": "search", "arguments": {"params": {"engine": "youtube", "search_query": "how to make espresso"}}}
{"name": "search", "arguments": {"params": {"engine": "apple_app_store", "term": "habit tracker"}}}
{"name": "search", "arguments": {"params": {"engine": "ebay", "_nkw": "vintage mechanical keyboard"}}}

Unterstützte Suchmaschinen: Google, Bing, Yahoo, DuckDuckGo, YouTube, eBay und mehr (siehe serpapi://engines).

Ergebnistypen: Antwortfelder, organische Ergebnisse, Nachrichten, Bilder, Shopping – werden automatisch erkannt und formatiert.

Suchantworten behalten den vorhandenen MCP-String structuredContent.result bei und enthalten denselben String im Textinhalt. Bei JSON-Ausgaben enthält result serialisiertes JSON; bestehende Clients können es weiterhin mit JSON.parse(response.structuredContent.result) parsen. Bei Markdown-Ausgaben enthält es das unveränderte Markdown. Fehler und Abbrüche verwenden dieselbe Hülle. Bei Fehlern während der Suchausführung wird isError: true gesetzt. Clients, die FastMPs High-Level-call_tool() verwenden, sollten ToolError behandeln oder mit call_tool_mcp() das Ergebniskennzeichen prüfen. Siehe MCP-Toolergebnisse.

search verwendet den Suchmaschinenkatalog und suchmaschinenspezifische Regeln, um fehlende Parameter zu ermitteln. Clients, die MCP 2026-07-28 unterstützen, erhalten ein Formular, bevor eine Suche ausgeführt wird. Akzeptierte Antworten werden validiert; bei Ablehnung oder Abbruch wird keine Suche ausgeführt. Ältere Clients und Clients ohne Formularabfrage erhalten einen Fehler mit den fehlenden Parametern, damit der Agent im Gespräch danach fragen kann. Siehe MCP-Eingabeanforderungen.

• Google Flights: Abflug- und Ankunftskennungen, Abflugdatum und bei Hin- und Rückflügen ein Rückflugdatum. Datumsangaben und Flughafenkennungen werden überprüft. Tokenbasierte Suchen, Reisen mit mehreren Zwischenstopps und selected_flights_json behalten ihr bisheriges Verhalten bei.
• Google Hotels: Reiseziel oder Hotelanfrage, Anreisedatum und Abreisedatum. Das Abreisedatum muss nach dem Anreisedatum liegen. Gästezahlen und andere optionale Filter behalten die vom Aufrufer angegebenen Werte oder die API-Standardwerte bei.
• Google Maps Directions: fehlende Start- und Zieladressen. Bereits angegebene Koordinaten oder Ortsdaten-IDs erfüllen die Anforderungen für den jeweiligen Endpunkt.
• Andere Suchmaschinen aus dem Katalog verwenden ihre Pflichtfelder, etwa search_query von YouTube, find_loc von Yelp und k von Amazon. Die Suchmaschinenregeln berücksichtigen bekannte Standardwerte und Alternativen, darunter Amazon-Kategorieknoten, eBay-Kategorien und Zitationssuchen in Google Scholar.

Ergibt sich aus einer Antwort eine weitere Anforderung, listet das Tool die verbleibenden Felder auf, die der Agent in einem neuen Aufruf angeben muss. Formulare unterstützen Zeichenfolgen, Zahlen, boolesche Werte und Einzelauswahlfelder; für nicht unterstützte komplexe Felder wird der Fehler für fehlende Parameter ausgegeben. Unbekannte Suchmaschinen werden an SerpApi weitergeleitet.

Extraktionstool

Das Tool extract liest Webseiten und gibt deren Inhalte als strukturiertes JSON oder Markdown zurück. Sie können eine einzelne Seite extrahieren, die URLs einer Website ermitteln oder mehrere Seiten crawlen. Alle verfügbaren Parameter finden Sie in der Extract-API-Referenz oder in der Ressource serpapi://engines/extract.

Einige verfügbare Parameter:

• params.url (erforderlich): URL einer Seite oder Website
• params.mode: Extraktionsmodus; "scrape" (Standard) liest eine Seite, "map" ermittelt URLs und "crawl" extrahiert mehrere Seiten
• params.include_markdown: Seiteninhalt als Markdown einschließen; standardmäßig true für Scrape und Crawl, oder zum Deaktivieren auf false setzen
• params.output: Antwortformat; standardmäßig "json" im vollständigen Modus und "md" im kompakten Modus. Legen Sie den Wert explizit fest, um das Format zu überschreiben.
• params.max_pages: Maximale Anzahl der zu crawlenden Seiten, einschließlich der Startseite (Standard: 10, Maximum: 100)
• params.json_restrictor: Auszuwählende Felder, z. B. "markdown,error"
• mode: Antwortmodus; "complete" (Standard) gibt die vollständige Antwort zurück. "compact" verwendet standardmäßig natives Markdown. Bei explizitem params.output="json" behält die kompakte Extraktion einer einzelnen Seite das oberste Feld markdown bei, sofern vorhanden, und enthält API-Fehler weiterhin. Antworten ohne Markdown, einschließlich Ergebnissen, die an eine andere Suchmaschine weitergeleitet wurden, behalten ihre Daten bei, während Metadaten entfernt werden. Bei Verwendung von JSON haben explizite Werte für params.json_restrictor und params.include_markdown=false Vorrang. Bei Maps und Crawl entfernt kompaktes JSON die Metadaten. Markdown-Ausgaben werden unverändert zurückgegeben.

Beispiele:

{"name": "extract", "arguments": {"params": {"url": "https://example.com"}}}
{"name": "extract", "arguments": {"params": {"url": "https://example.com"}, "mode": "compact"}}
{"name": "extract", "arguments": {"params": {"url": "https://example.com", "output": "md"}}}
{"name": "extract", "arguments": {"params": {"url": "https://example.com", "mode": "map"}}}
{"name": "extract", "arguments": {"params": {"url": "https://example.com", "mode": "crawl", "max_pages": 2}}}

Für den Inhalt einer einzelnen Seite als natives Markdown verwenden Sie mode="compact". Fügen Sie params.output="json" hinzu, um JSON mit dem Feld markdown zu erhalten. Vollständiges JSON enthält dieses Feld standardmäßig; Crawl-JSON enthält es in jedem Eintrag pages. Wenn Sie params.output="json" und params.include_markdown=false festlegen, bleiben die übrigen strukturierten Felder ohne Markdown erhalten.

Bei einem nicht zwischengespeicherten Aufruf verbraucht das Crawlen pro erfolgreich extrahierter Seite einen Suchcredit. Verwenden Sie params.max_pages, um die Anzahl der extrahierten Seiten zu begrenzen.

Interaktive Benutzeroberfläche (MCP Apps)

Das Tool search gibt standardmäßig JSON zurück. Für Hosts, die die MCP-Apps-Erweiterung (SEP-1865) unterstützen, stellen zwei optionale Tools Ergebnisse direkt im Gespräch als interaktive Benutzeroberfläche dar. Dadurch gelangt das umfangreiche SERP-JSON nicht in das Kontextfenster des Modells:

• search_table: Organische Ergebnisse als sortierbare, durchsuchbare Tabelle.
• search_dashboard: Zusammenfassende Kennzahlen, ein Diagramm zur Quellenaufteilung und eine Ergebnistabelle mit einem Detailbereich, der sich per Klick aufklappen lässt.

Beide akzeptieren dasselbe params wie search. Hosts, die MCP Apps nicht unterstützen, ignorieren diese Tools einfach.

Fehlerbehebung

• „API-Schlüssel fehlt“: Schlüssel im URL-Pfad /{YOUR_KEY}/mcp oder im Header Bearer YOUR_KEY angeben
• „Ungültiger Schlüssel“: Unter serpapi.com/dashboard überprüfen
• „Ratenlimit überschritten“: Warten oder Ihren SerpApi-Tarif upgraden
• „Keine Ergebnisse“: Eine andere Suchanfrage oder Suchmaschine ausprobieren

Datenschutzrichtlinie

• Gesendet: nur die Parameter, die der MCP-Host an einen Toolaufruf übergibt. Der Server sieht weder den übrigen Gesprächsverlauf noch Dateien, Speicher oder Verlauf auf dem Host.
• Weitergeleitet: Jede Suche wird mit Ihrem API-Schlüssel an serpapi.com gesendet; die Ergebnisse werden unverändert zurückgegeben. Informationen zum Umgang von SerpApi mit Suchanfragen und Konten finden Sie in der SerpApi-Datenschutzrichtlinie.
• Gespeichert: mcp.serpapi.com erfasst Anfragemetriken (Methode, Statuscode, Dauer) und speichert weder Suchanfragen noch Ergebnisse. Ein Schlüssel im URL-Pfad kann in Anforderungsprotokollen erscheinen; verwenden Sie daher vorzugsweise den Header.
• Lokales Bundle: Die Claude Desktop-Erweiterung wird auf Ihrem Rechner ausgeführt, speichert den Schlüssel in den Einstellungen von Claude Desktop und ruft serpapi.com direkt auf. Nichts wird über mcp.serpapi.com geleitet.
• Kontakt: privacy@serpapi.com oder erstellen Sie ein Issue.

Mitwirken

Unter CONTRIBUTING.md finden Sie Informationen zur Entwicklungsumgebung, zu Befehlen zum Aktualisieren des Schemas, zu Tests, Docker- und MCP-Bundle-Builds sowie zu Releases.

Lizenz

MIT-Lizenz – Einzelheiten finden Sie in der Datei LICENSE.