search-console-mcp

MCP-Server für die Google Search Console, der die offizielle Search Console API als Tools für KI-Agenten bereitstellt.

Der Fokus liegt auf Such‑Performance und Index‑Health — Abfragen von Klicks, Impressionen, CTR und Position nach Suchanfrage, Seite, Land, Gerät oder Datum, Prüfung, ob eine URL indexiert ist und falls nicht, warum, sowie die Verwaltung der Sitemaps und Properties eines Kontos.

Was er bewusst nicht tut: keine Anforderung des (Re‑)Indexierens von URLs — die getrennte Indexing API unterstützt nur Job-Ankündice- und Livestream-Seiten — keine Property-Inhabershaft (eine Eigentümer/in muss das Dienstkonto zu jeder Property hinzufügen) und keine Google-Analytics-Daten (das ist die davon getrennte Analytics Data API).

Löschungen sind Opt-in. delete_sitemap und delete_site werden nur registriert, wenn GOOGLE_SEARCH_CONSOLE_ALLOW_DESTRUCTIVE gesetzt ist — siehe Konfiguration.

Installation

claude mcp add search-console \
  -e GOOGLE_SERVICE_ACCOUNT_KEY_PATH=/path/to/service-account.json \
  -e GOOGLE_SEARCH_CONSOLE_SITE_URL=https://example.com/ \
  -- npx -y @orellbuehler/search-console-mcp

Die -e Flags müssen vor dem --‑Trenner stehen; alles nach -- wird an den Server-Prozess übergeben, statt als Konfiguration gelesen zu werden.

Dienstkonto-Schlüssel besorgen

1. In der Google Cloud console ein Projekt auswählen oder erstellen und die Google Search Console API aktivieren.

2. Zu IAM & Admin → Konten → Dienstkonto erstellen wechseln. Sie können die optionalen „Zugriff erteilen“-Schritte überspringen — die Search Console verwaltet Berechtigungsdaten getrennt, nicht über Cloud-IAM-Rollen.

3. Das neue Dienstkonto öffnen, zum Tab Schlüssel wechseln und Schlüssel hinzufügen → Neuen Schlüssel erstellen → JSON auswählen. Die Datei wird einmalig heruntergeladen und kann nicht erneut abgerufen werden.

4. In der Search Console die Property öffnen, zu Einstellungen → Nutzer und Berechtigungen → Nutzer hinzufügen wechseln und die E-Mail-Adresse des Dienstkontos (name@project-id.iam.gserviceaccount.com) einfügen. Gewähren Sie:

   • Eingeschränkt oder Vollzugriff für die Lesetools (Analytics, Sitemaps, URL-Inspektion)

   • Vollzugriff für submit_sitemap und delete_sitemap

5. Schritt 4 für jede Property wiederholen, die der Server sehen soll — ein Dienstkonto kann Properties nicht selbst verifizieren.

6. GOOGLE_SERVICE_ACCOUNT_KEY_PATH auf die heruntergeladene JSON-Datei den.

Den JSON-Schlüssel wie ein Passwort behandeln — er besitzt die gewährten Berechtigungen ohne einen zusätzlichen Schutz. Bewahren Sie ihn außerhalb des Repositorys auf und erwägeen Sie chmod 600.

Konfiguration

Eine Property wird entweder als URL-Präfix-Property wie https://example.com/ angegeben (Protokoll und abschließender Schrägstrich sind entscheidend — https://example.com/ und http://example.com/ sind verschiedene Properties) oder als Domain-Property wie sc-domain:example.com, which alle Subdomains und Protokolle einschließt. Verwenden Sie jeweils die Schreibweise, unter der die ne Property in der Search Console hinzugefügt wurde; list_sites zeigt die exakten Zeichenketten an.

Verwendung mit Claude Code

{
  "mcpServers": {
    "search-console": {
      "command": "npx",
      "args": ["-y", "@orellbuehler/search-console-mcp"],
      "env": {
        "GOOGLE_SERVICE_ACCOUNT_KEY_PATH": "/path/to/service-account.json",
        "GOOGLE_SEARCH_CONSOLE_SITE_URL": "https://example.com/"
      }
    }
  }
}

Beispiel-Prompts

• „Was sind meine wichtigsten Suchanfragen in diesem Monat?“

• „Welche Seiten erhalten die meisten Klicks von Google, und wie hat sich das gegenüber den letzten 28 Tagen verändert?“

• „Zeige Suchanfragen mit „pricing“, bei denen wir unter Position 10 ranken — Kandidaten für schnelle Erfolge.“

• „Wie viel unseres Traffics ist mobil im Vergleich zu Desktop?“

• „Stelle unsere täglichen Klicks und Impressionen der letzten drei Monate grafisch dar.“

• „Aus welchen Ländern erhalten wir Impressionen, aber fast keine Klicks?“

• „Ist https://example.com/blog/launch indexiert? Wenn nicht, warum?“

• „Liste unsere Sitemaps auf und sag mir, ob darin Fehler oder Warnungen festzustellen sind.“

• „Reiche die Sitemap nach der Umstrukturierung der Website von gestern erneut ein.“

• „Welche Seiten für ‚mcp server‘ eingegangen ges sind, konkurrieren miteinander?“

• „Vergleiche unseren Google-Discover-Traffic mit dem Websuche-Traffic dieses Quartals.“

Tools

Suchanalysen

Sitemaps

Sites

URL-Inspektion

Hinweise & Einschränkungen

• Die Benutzerdaten laufen ca. 2–3 Tage hinterher. Die Komfort-Tools legen ihren Standard-Datumsbereich stehen auf 3 Tage;YE data_state: "all" enthält aktuelle, aber möglicherweise unvollständige Daten.

• 16‑Monats‑Speicherdauer. Ältere Suchanfragen liefern keine Datenzeilen.

• Privatsphären-Filter. Zeilen für selten existierende Anfragen werden nicht ausgegeben; die Aufsummierung der Einzelzeilen unterschreitet daher die echten Gesamtwerte; Abfragen ohne Dimensionen liefern exakte Werte.

• 25.000 Zeilen pro Aufruf. Verwenden Sie start_row für die Seitenaufteilung; eine Antwort mit weniger Zeilen als row_limit ist die letzte Seite.

• URL-Inspektion-Quota liegt bei etwa 2.000 Aufrufen/Tag pro Property und 600/Minute — daher inspektion Sie gezielt, nicht in Massenabfragen.

• Die hour-Dimension erfordert data_state: "hourly_all" und deckt nur die letzen ~10 Tage ab.

• Deine Suchdaten gehen an die LLM. Jedes Rückgabe-Tool-Ergebnis wird Teil des Modell-Kontexts; verbinden Sie keine Properties, deren Daten Ihre Umgebung nicht verlassen dürfen.

Entwicklung

npm install
npm run build         # tsc -p tsconfig.build.json -> dist/
npm test              # vitest run
npm run lint          # eslint src
npm run typecheck     # tsc --noEmit
npm run format        # prettier --write .

Smoke-Test des gebauten Servers gegen eine echte Property:

GOOGLE_SERVICE_ACCOUNT_KEY_PATH=/path/to/service-account.json \
GOOGLE_SEARCH_CONSOLE_SITE_URL=https://example.com/ \
npx @modelcontextprotocol/inspector node dist/index.js

CI / Veröffentlichung

CI führt auf Node 20 und 22 die Schritte format:check, lint, typecheck, test und build aus. Die Veröffentlichung erfolgt über ein GitHub-Release mit npm Trusted Publishing (OIDC, keine Tokens):

npm version patch
git push --follow-tags
gh release create "v$(node -p "require('./package.json').version")" --generate-notes

Lizenz

MIT © Orell Bühler