mcp-google-gsc

MCP-Server für Google Search Console – Suchanalysen, URL-Inspektion und Site-Verwaltung über Claude.

Funktionen

• Suchanalysen – Abfrage von Klicks, Impressionen, CTR und Position mit flexiblen Dimensionsfiltern (query, page, device, country, date)

• URL-Inspektion – Prüfen des Indexierungsstatus, der mobilen Benutzerfreundlichkeit und der Rich Results für jede URL

• Site-Listing – Auflistung aller verifizierten Search-Console-Properties, die für Ihr authentifiziertes Konto zugänglich sind (OAuth-Benutzer oder Dienstkonto)

• Multi-Client-Unterstützung – Verwaltung mehrerer GSC-Properties mit Verzeichnis-basierter Konfigurationszuordnung

Related MCP server: Google Search Console MCP Server

Installation

Von npm

npm install mcp-google-gsc

Aus dem Quellcode

git clone https://github.com/mharnett/mcp-search-console.git
cd mcp-google-gsc
npm install
npm run build

Konfiguration

Sicherheit: Teilen Sie Ihre .mcp.json-Datei niemals und committen Sie sie nicht in Git – sie kann API-Anmeldedaten enthalten. Fügen Sie .mcp.json zu Ihrer .gitignore hinzu.

mcp-gsc unterstützt zwei Authentifizierungsmodi. Wählen Sie den, der zu Ihrer Einrichtung passt. Keiner erfordert eine Datei an einem fest codierten maschinenlokalen Pfad – die Anmeldedaten stammen aus Umgebungsvariablen (oder einer von Ihnen erstellten config.json).

Welchen Modus verwenden:

• Dienstkonto (Modus B) – empfohlen für unbeaufsichtigten / Server- / Headless-Einsatz. Ein Dienstkonto hat keine interaktive Anmeldung, die abläuft oder erneut genehmigt werden muss, daher ist es die richtige Wahl für Dauerbetrieb. Die einzige Einrichtungsanforderung besteht darin, dass die E-Mail-Adresse des Dienstkontos Zugriff auf jede Search-Console-Property erhalten muss, die Sie abfragen möchten (siehe Modus B).

• Benutzer-OAuth (Modus A) – für persönlichen / interaktiven Gebrauch, wenn Sie sich mit Ihrem eigenen Google-Login autorisieren möchten.

Priorität, wenn beide konfiguriert sind: Wenn eine Dienstkontoschlüsseldatei explizit festgelegt ist (GOOGLE_APPLICATION_CREDENTIALS oder credentials_file in config.json), hat sie Vorrang vor jedem OAuth-Refresh-Token oder gespeicherten OAuth-Anmeldedaten. Wenn keines konfiguriert ist, schlägt der Server beim Start laut mit einer Onboarding-Nachricht fehl, anstatt still zu raten – es gibt keinen maschinenlokalen Standard und kein stilles Laufzeit-Failover zwischen den Modi.

Modus A: Benutzer-OAuth (eigenes Google-Konto verwenden)

Verwenden Sie dies, wenn Sie sich mit Ihrem eigenen Google-Login autorisieren möchten (dem Konto, das Zugriff auf die Search Console hat). Am besten für persönlichen / interaktiven Gebrauch.

1. Erstellen Sie in der Google Cloud Console eine OAuth-2.0-Client-ID vom Typ Desktop-App und aktivieren Sie die Search Console API. (Für einen Desktop-App-Client akzeptiert Google jeden http://localhost-Loopback-Redirect – Sie müssen keinen Port vorab registrieren.)

2. Exportieren Sie Ihre Client-Anmeldedaten:

   export GOOGLE_GSC_CLIENT_ID=...apps.googleusercontent.com
   export GOOGLE_GSC_CLIENT_SECRET=...

3. Erstellen Sie ein Refresh-Token (öffnet Ihren Browser, verwendet PKCE + access_type=offline):

   node get-refresh-token.cjs

   Leiten Sie die Standardausgabe dieses Befehls nicht in ein gemeinsames Protokoll um – er gibt das Refresh-Token absichtlich auf stdout aus.

4. Kopieren Sie die gedruckte Zeile in Ihre Umgebung:

   export GOOGLE_GSC_REFRESH_TOKEN=...

Der Server liest GOOGLE_GSC_CLIENT_ID, GOOGLE_GSC_CLIENT_SECRET und GOOGLE_GSC_REFRESH_TOKEN zur Laufzeit aus der Umgebung.

Alternativ können Sie den geführten Helfer npx mcp-gsc-auth ausführen, der denselben PKCE-OAuth-Ablauf durchführt, Ihnen die Auswahl einer Standard-Search-Console-Property ermöglicht und das Ergebnis in eine benutzerspezifische Anmeldedatendatei schreibt.

Modus B: Dienstkonto (empfohlen für unbeaufsichtigten / Server-Einsatz)

Verwenden Sie dies für Server- / Headless- / Dauerbetrieb-Kontexte – es ist der empfohlene Weg, wenn kein Mensch anwesend ist, um eine interaktive Anmeldung abzuschließen oder zu erneuern.

1. Erstellen Sie ein Google Cloud Dienstkonto mit Zugriff auf die Search Console API und laden Sie dessen JSON-Schlüsseldatei herunter.

2. Gewähren Sie der E-Mail-Adresse des Dienstkontos Zugriff auf jede Search-Console-Property, die Sie abfragen möchten (fügen Sie es als Benutzer in der Search Console hinzu). Ohne diese Gewährung auf der Property kann sich das Dienstkonto zwar authentifizieren, sieht aber keine Websites.

3. Weisen Sie den Server über eine Umgebungsvariable auf die Schlüsseldatei hin (kein fest codierter Pfad):

   export GOOGLE_APPLICATION_CREDENTIALS=/path/to/your/service-account-key.json

OAuth-Bereich

Beide Modi fordern einen einzigen, schreibgeschützten Bereich an: https://www.googleapis.com/auth/webmasters.readonly. Alle vier Tools sind Lesezugriffe – nichts schreibt –, daher fragt der Server nie nach Lese-/Schreibzugriff.

Der Bereich ist einmal in config.json unter oauth.scope definiert (siehe config.example.json). Der OAuth-Helfer und die Laufzeit lesen denselben Wert, sodass sie nie voneinander abweichen. Wenn config.json fehlt (z. B. bei einer Neuinstallation), wird der festgelegte schreibgeschützte Standard verwendet.

Multi-Client-Konfiguration (optional)

Um Arbeitsverzeichnisse auf Search-Console-Properties abzubilden, erstellen Sie eine config.json im Projektstamm (siehe config.example.json):

{
  "oauth": {
    "scope": "https://www.googleapis.com/auth/webmasters.readonly"
  },
  "clients": {
    "my-project": {
      "name": "My Project",
      "folder": "/path/to/project",
      "site_url": "https://example.com/"
    }
  }
}

Verwendung

Fügen Sie zu Ihrer Claude-Code-.mcp.json hinzu:

{
  "mcpServers": {
    "gsc": {
      "command": "node",
      "args": ["/path/to/mcp-gsc/dist/index.js"]
    }
  }
}

Oder wenn global installiert:

{
  "mcpServers": {
    "gsc": {
      "command": "npx",
      "args": ["mcp-google-gsc"]
    }
  }
}

Claude Desktop: Fügen Sie zu ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) oder %APPDATA%\Claude\claude_desktop_config.json (Windows) hinzu.

Tools

gsc_search_analytics

Unterstützt Dimensionen: query, page, device, country, date. Filtern Sie nach jeder Dimension mit Operatoren wie equals, contains, notContains. Der Datumsbereich ist standardmäßig die letzten 28 Tage.

gsc_inspection

Gibt Indexabdeckung, Crawl-Status, Bewertung der mobilen Benutzerfreundlichkeit und Details zu Rich Results für eine bestimmte URL innerhalb einer Property zurück.

Architektur

• Resilienz – Verwendet cockatiel für Wiederholungen mit exponentiellem Backoff und Circuit-Breaker-Mustern bei allen Google-API-Aufrufen

• Protokollierung – Strukturierte Protokollierung über pino mit konfigurierbaren Protokollebenen

• Antwortverarbeitung – Antworten werden auf 200 KB gekürzt, um innerhalb der MCP-Transportgrenzen zu bleiben

Lizenz

MIT – siehe LICENSE.

Erstellt von Mark Harnett / drak-marketing