SerpApi MCP

SerpApi MCP Server

Eine Model Context Protocol (MCP) Server-Implementierung, die in SerpApi integriert ist und umfassende Suchmaschinenergebnisse sowie Datenextraktion ermöglicht.

Funktionen

• Multi-Engine-Suche: Google, Bing, Yahoo, DuckDuckGo, YouTube, eBay und weitere
• Engine-Ressourcen: Parameterschemata pro Engine über MCP-Ressourcen verfügbar (siehe Such-Tool)
• Echtzeit-Wetterdaten: Standortbasiertes Wetter mit Vorhersagen über Suchanfragen
• Aktienmarktdaten: Unternehmenskennzahlen und Marktdaten über die Suchintegration
• Dynamische Ergebnisverarbeitung: Erkennt und formatiert automatisch verschiedene Ergebnistypen
• Flexible Antwortmodi: Vollständige oder kompakte JSON-Antworten
• JSON-Antworten (Standard): Strukturierte JSON-Ausgabe mit vollständigem oder kompaktem Modus
• Markdown-Antworten: Reduziert Token-Nutzung um durchschnittlich 50 % und um mehr als 90 % bei APIs mit komplexem verschachteltem JSON.
• Interaktive Benutzeroberfläche (MCP-Apps): Optionale search_table- und search_dashboard-Tools, die Ergebnisse in unterstützenden Hosts als interaktive Benutzeroberfläche rendern
• 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. Ihren API-Schlüssel finden Sie auf 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

Selbsthosting

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 (oder erstellen Sie es wie unten beschrieben) 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 sensible Einstellung und führt den Server lokal über stdio aus. Das Bundle verwendet die MCPB-uv-Laufzeit: Es enthält nur den Quellcode, pyproject.toml und uv.lock, und Claude Desktop stellt Python und die festgelegten Abhängigkeiten zur Installationszeit mit uv bereit. Es wird also nichts mitgeliefert, und ein Bundle funktioniert auf macOS, Windows und Linux.

uv run mcpb/build.py   # needs Node.js for the MCPB CLI; writes dist/serpapi-mcp-<version>.mcpb

Alles, was mit dem Bundle zusammenhängt, befindet sich in mcpb/ sowie .mcpbignore im Projektstamm. Der Build generiert die Engine-Schemata aus dem SerpApi-Playground neu (--no-rebuild-engines bündelt engines/ stattdessen aus dem Arbeitsbaum), validiert mcpb/manifest.json, packt die git-verfolgten Dateien abzüglich .mcpbignore mit dem Manifest im Bundle-Stamm, installiert es dann in ein temporäres Verzeichnis und startet es über stdio, um sicherzustellen, dass es funktioniert (--no-smoke überspringt diesen letzten Schritt). Das Bundle wird nur zur Veröffentlichung erstellt: Das Pushen eines v<version>-Tags startet den Release-Workflow, der die Testsuite ausführt und dann den gehosteten Server bereitstellt, den MCP-Registry-Eintrag veröffentlicht und das Bundle erstellt und an die GitHub-Version anhängt. Pull-Requests führen die Manifest- und stdio-Einstiegspunkt-Tests in tests/test_mcpb.py aus, packen jedoch kein Bundle.

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

Zwei Methoden werden unterstützt:

• Header-basiert: Authorization: Bearer YOUR_API_KEY (empfohlen: Der Schlüssel bleibt außerhalb von URLs und Protokollen)
• Pfad-basiert: /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 '...'

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

Such-Tool

Der MCP-Server verfügt über ein Hauptsuch-Tool, das alle SerpApi-Engines und Ergebnistypen unterstützt. Alle verfügbaren Parameter finden Sie in der SerpApi-API-Referenz. Engine-Parameterschemata werden auch als MCP-Ressourcen bereitgestellt: serpapi://engines (Index) und serpapi://engines/<engine>. Clients, die Argumentvervollständigung unterstützen, können Engine-Namensvorschläge für serpapi://engines/{engine_name} anfordern. Beispielsweise schlägt das Präfix google_f passende Engine-Identifikatoren vor. Dies vervollständigt den Ressourcen-URI-Parameter, nicht beliebige Suchanfragen.

Die Parameter, die Sie angeben können, sind für jede API-Engine spezifisch. 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 (Standard) weglassen oder für Markdown auf "md" setzen
• mode: Antwortmodus; "compact" entfernt Metadaten aus JSON, während Markdown unverändert zurückgegeben wird
• ...weitere Parameter 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 Engines: Google, Bing, Yahoo, DuckDuckGo, YouTube, eBay und weitere (siehe serpapi://engines).

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

Suchantworten bewahren die vorhandene MCP-structuredContent.result-Zeichenfolge und enthalten dieselbe Zeichenfolge im Textinhalt. Für JSON-Ausgabe enthält result serialisiertes JSON; bestehende Clients können es weiterhin mit JSON.parse(response.structuredContent.result) parsen. Für Markdown-Ausgabe enthält es das unveränderte Markdown. Fehler und Abbrüche verwenden denselben Wrapper. Fehler bei der Suchausführung setzen isError: true; Clients, die FastMCPs High-Level-call_tool() verwenden, sollten ToolError behandeln oder call_tool_mcp() verwenden, um das Ergebnis-Flag zu prüfen. Siehe MCP-Tool-Ergebnisse.

search verwendet den Engine-Katalog und enginespezifische Regeln, um fehlende Parameter zu identifizieren. Clients, die MCP 2026-07-28 unterstützen, erhalten ein Formular, bevor eine Suche ausgeführt wird. Akzeptierte Antworten werden validiert; Ablehnung oder Abbruch führt zu keiner Suche. Legacy-Clients und Clients ohne Formularabfrage erhalten einen Fehler mit den fehlenden Parametern, damit der Agent sie im Gespräch erfragen kann. Siehe MCP-Eingabeanforderungen.

• Google Flights: Abflug- und Ankunfts-Identifikatoren, Abflugdatum und ein Rückflugdatum für Hin- und Rückflüge. Daten und Flughafen-Identifikatoren werden geprüft. Token-basierte Suchen, Multi-City-Reiserouten und selected_flights_json behalten ihr bestehendes Verhalten bei.
• Google Hotels: Ziel- oder Hotelanfrage, Check-in-Datum und Check-out-Datum. Check-out muss nach Check-in folgen. Gästezahlen und andere optionale Filter behalten die Werte des Aufrufers oder die API-Standardwerte bei.
• Google Maps Directions: fehlende Start- und Zieladressen. Bereits angegebene Koordinaten oder Ortsdaten-IDs erfüllen den entsprechenden Endpunkt.
• Andere Katalog-Engines verwenden ihre Pflichtfelder, wie YouTubes search_query, Yelps find_loc und Amazons k. Engine-Regeln berücksichtigen bekannte Standardwerte und Alternativen, einschließlich Amazon-Kategorieknoten, eBay-Kategorien und Google-Scholar-Zitationssuchen.

Das Formular wird aus den ursprünglichen Argumenten jeder Anfrage abgeleitet. Es verwendet kein requestState oder prozesslokalen Fortsetzungsspeicher, sodass ein Wiederholungsversuch auf einer anderen Replik ohne gemeinsamen Zustandsschutzschlüssel ausgeführt werden kann. Die Authentifizierung wird bei jeder HTTP-Anfrage angewendet, und nur Antworten für angeforderte Felder werden verwendet. Wenn eine Antwort eine weitere Anforderung einführt, listet das Tool die verbleibenden Felder auf, die der Agent in einem neuen Aufruf bereitstellen soll.

Um die geführte Suche zu erweitern, fügen Sie Pflichtfelder, Beschreibungen, Typen und Optionen zur engines/<engine>.json-Datei der Engine hinzu. Fügen Sie einen EngineInputRules-Eintrag in src/engine_input_rules.py hinzu, wenn Anforderungen von anderen Parametern, Standardwerten oder Alternativen abhängen. Der gemeinsame MCP-Handler in src/search_input.py benötigt keine enginespezifischen Verzweigungen. Formulare unterstützen Zeichenfolgen, Zahlen, boolesche Werte und Einzelauswahlfelder; nicht unterstützte komplexe Felder erhalten den Fehler für fehlende Parameter. Unbekannte Engines werden an SerpApi durchgereicht.

Interaktive Benutzeroberfläche (MCP-Apps)

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

• search_table: organische Ergebnisse als sortierbare, durchsuchbare Tabelle.
• search_dashboard: Zusammenfassungsmetriken, ein Diagramm zur Quellenaufschlüsselung und eine Ergebnistabelle mit einem Detailbereich zum Aufklappen per Klick.

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

Vorschau lokal ohne MCP-Host:

uv run fastmcp dev apps src/server.py

Entwicklung

# Local development
uv sync && uv run src/server.py

# Docker
docker build -t serpapi-mcp . && docker run -p 8000:8000 serpapi-mcp

# Build the Claude Desktop extension (MCP Bundle); rebuilds engines, needs Node.js for the MCPB CLI
uv run mcpb/build.py

# Release: update pyproject.toml, server.json, mcpb/manifest.json and uv.lock together.
uv run --no-sync scripts/bump_version.py 2.0.0
# Review and commit the changes before tagging the release.
# Nothing ships on a plain push to main. The tag runs the release workflow, which runs the test
# suite and then deploys the hosted server, publishes server.json to the MCP Registry, and builds
# the MCP Bundle and attaches it to the GitHub release.
git tag v2.0.0 && git push origin v2.0.0

# Regenerate engine resources (Playground scrape)
python build-engines.py

# Testing with MCP Inspector
npx @modelcontextprotocol/inspector
# Configure: URL mcp.serpapi.com/YOUR_KEY/mcp, Transport "Streamable HTTP transport"

Fehlerbehebung

• "API-Schlüssel fehlt": Schlüssel im URL-Pfad /{YOUR_KEY}/mcp oder Header Bearer YOUR_KEY einfügen
• "Ungültiger Schlüssel": Überprüfen Sie serpapi.com/dashboard
• "Ratenlimit überschritten": Warten Sie oder erweitern Sie Ihren SerpApi-Plan
• "Keine Ergebnisse": Versuchen Sie eine andere Anfrage oder Engine

Datenschutzrichtlinie

• Gesendet: nur die Parameter, die der MCP-Host an einen Tool-Aufruf übergibt. Der Server sieht nie den Rest des Gesprächs oder Dateien, Speicher oder Verlauf auf dem Host.
• Weitergeleitet: Jede Suche geht mit Ihrem API-Schlüssel an serpapi.com; Ergebnisse kommen unverändert zurück. Siehe die SerpApi-Datenschutzrichtlinie für Informationen, wie SerpApi Suchen und Konten behandelt.
• Aufbewahrt: mcp.serpapi.com zeichnet Anforderungsmetriken (Methode, Statuscode, Dauer) auf und speichert keine Anfragen oder Ergebnisse. Ein Schlüssel im URL-Pfad kann in Anforderungsprotokollen erscheinen, daher den Header bevorzugen.
• Lokales Bundle: Die Claude-Desktop-Erweiterung läuft auf Ihrem Rechner, bewahrt den Schlüssel in den Claude-Desktop-Einstellungen und ruft serpapi.com direkt auf. Nichts läuft über mcp.serpapi.com.
• Kontakt: privacy@serpapi.com oder öffnen Sie ein Issue.

Mitwirken

1. Repository forken
2. Feature-Branch erstellen: git checkout -b feature/amazing-feature
3. Abhängigkeiten installieren: uv install
4. Änderungen vornehmen
5. Änderungen committen: git commit -m 'Add amazing feature'
6. Zum Branch pushen: git push origin feature/amazing-feature
7. Pull-Request öffnen

Lizenz

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