gsc-mcp-connector

Selbst gehosteter Google Search Console MCP-Server, in 15 Minuten auf Cloudflare Workers bereitstellbar. Stecken Sie ihn in ChatGPT, Claude oder einen anderen MCP-fähigen Client und fragen Sie Ihre GSC-Daten in natürlicher Sprache ab.

Was Sie damit bekommen

Nach der Bereitstellung erhalten Sie einen privaten MCP-Endpunkt, der Ihrem KI-Assistenten 4 Tools zur Verfügung stellt:

• list_sites — entdecken Sie jede Eigenschaft, auf die der authentifizierte Benutzer zugreifen kann

• query_search_analytics — Klicks, Impressionen, CTR, Position, filterbar nach Suchanfrage / Seite / Land / Gerät / Suchdarstellung / Datum

• inspect_url — vollständige URL Inspection API-Ausgabe (Indexierungsstatus, kanonisch, mobil, AMP)

• list_sitemaps — jede eingereichte Sitemap und deren Verarbeitungsstatus

Sie fragen: „Welche sind meine 50 Anfragen mit dem größten Klickverlust zwischen den letzten 28 Tagen und den 28 Tagen davor?" und der Assistent holt die Daten, berechnet die Differenz und schreibt die Analyse. Kein SQL-Export mehr.

Related MCP server: gsc-mcp-connector

Wie es funktioniert

ChatGPT/Claude  ──OAuth──▶  Your Worker  ──OAuth──▶  Google
                                 │
                                 └─ holds your Google refresh_token
                                    (encrypted, in OAuth grant props)

Zwei OAuth-Ketten:

1. MCP-Client → Worker: ChatGPT/Claude führen OAuth 2.1 + PKCE gegen Ihren Worker durch. Die Login-Oberfläche fragt nach einem statischen „Zugriffsschlüssel", den Sie bei der Bereitstellung festlegen (die Connector-Gate).

2. Worker → Google: Nach der Zugriffsschlüsselprüfung wird der Benutzer zum Google-Zustimmungsbildschirm weitergeleitet, um webmasters.readonly zu gewähren. Das resultierende Aktualisierungstoken wird in der OAuth-Genehmigung gespeichert; bei jedem Tool-Aufruf erneuert der Worker ein frisches Zugriffstoken und ruft GSC auf.

Das Google-Konto des Benutzers steuert den Zugriff – kein Service Account, kein GSC-Benutzermanagement, keine Berechtigungsverzögerung.

Voraussetzungen

Das kostenlose Cloudflare Workers-Kontingent (100.000 Anfragen/Tag) reicht für den persönlichen SEO-Einsatz völlig aus. Kein kostenpflichtiger Cloudflare-Tarif nötig.

Schnellstart (~15 Min.)

1. Den Worker bereitstellen

Klicken Sie oben in dieser README auf den Button Auf Cloudflare bereitstellen. Cloudflare klont das Repository in Ihr Konto, installiert Abhängigkeiten und gibt Ihnen eine öffentliche URL wie https://gsc-mcp-connector.<your-subdomain>.workers.dev.

Hinweis: In diesem Schritt werden Sie nach MCP_BEARER_TOKEN, GOOGLE_OAUTH_CLIENT_ID und GOOGLE_OAUTH_CLIENT_SECRET gefragt. Sie haben die Google-Werte noch nicht – füllen Sie MCP_BEARER_TOKEN vorerst mit einem beliebigen zufälligen Hex-String (später änderbar) und fügen Sie in die beiden Google-Felder irgendetwas ein. Wir werden sie in Schritt 4 richtig setzen.

Wenn Sie den Button überspringen möchten, klonen Sie das Repository lokal, führen Sie npm install und dann npx wrangler deploy aus.

Notieren Sie nach der Bereitstellung Ihre Worker-URL. Sie wird sowohl in Schritt 3 als auch in Schritt 5 benötigt.

2. Einen Connector-Zugriffsschlüssel generieren

Dies ist ein statischer zufälliger String, der als Tor vor Google OAuth dient. Jeder, der den Connector nutzt, muss diesen String in der Login-Oberfläche einfügen.

openssl rand -hex 32

Speichern Sie die Ausgabe – Sie werden ihn als Geheimnis festlegen und in ChatGPT/Claude verwenden.

3. Google Cloud einrichten (OAuth-Client)

Folgen Sie der Schritt-für-Schritt-Anleitung in docs/SETUP_GCP.md. Verwenden Sie Ihre Worker-URL aus Schritt 1 in der autorisierten Weiterleitungs-URI. Sie erhalten eine Client-ID und ein Client-Secret.

Dies ist der längste Schritt (~10 Min. beim ersten Mal), aber Sie führen ihn nur einmal durch.

4. Worker-Geheimnisse konfigurieren

npx wrangler secret put MCP_BEARER_TOKEN
# paste the value from step 2

npx wrangler secret put GOOGLE_OAUTH_CLIENT_ID
# paste the Client ID from step 3

npx wrangler secret put GOOGLE_OAUTH_CLIENT_SECRET
# paste the Client Secret from step 3

Oder über das Cloudflare-Dashboard: Workers & Pages → Ihr Worker → Settings → Variables and Secrets → fügen Sie jedes als Typ Secret hinzu.

Tipp – Kodierungsproblem unter Windows: Wenn Sie den Inhalt einer Datei weiterleiten (z. B. Get-Content | wrangler secret put) und diese Datei ein UTF-8-BOM hat, gelangt das BOM in Ihr Geheimnis und unterbricht die JSON-Analyse. Das Cloudflare-Dashboard oder interaktives wrangler secret put (Einfügen in die Eingabeaufforderung) vermeidet dies vollständig.

5. In ChatGPT einbinden (Plus/Pro/Team)

ChatGPT → Settings → Connectors → Add custom connector:

• Name: gsc

• MCP Server URL: https://YOUR-WORKER-URL/mcp (muss auf /mcp enden)

• Authentication: OAuth

• Aktivieren Sie „I understand and want to continue"

• Create

Ein Popup öffnet die Login-Oberfläche Ihres Workers. Fügen Sie Ihren MCP_BEARER_TOKEN ein → klicken Sie Continue with Google → → Google bittet Sie um Anmeldung (verwenden Sie das Konto, dem Ihre GSC-Eigenschaft gehört) und um die Genehmigung von webmasters.readonly → Sie werden zurück zu ChatGPT geleitet, der Connector ist aktiv.

Aktivieren Sie in einem neuen Chat den gsc-Connector in der Symbolleiste und fragen Sie: „Liste meine Google Search Console-Seiten auf". Sie sollten Ihre Eigenschaften sehen.

6. (Optional) In Claude.ai einbinden (Pro/Team)

Settings → Integrations → Add custom integration → gleiche URL, gleicher Ablauf.

Lokale Entwicklung

git clone https://github.com/JuJu78/gsc-mcp-connector
cd gsc-mcp-connector
npm install
cp .dev.vars.example .dev.vars
# edit .dev.vars with your real Client ID + Client Secret + bearer token
npx wrangler dev

Der Entwicklungsserver läuft auf http://localhost:8787. Beachten Sie, dass die lokale Entwicklung den Google OAuth-Ablauf nicht vollständig abschließen kann, da Google für Weiterleitungs-URIs HTTPS erfordert. Für einen echten End-to-End-Test stellen Sie auf Cloudflare bereit und testen Sie gegen die workers.dev-URL.

Einschränkungen

• Nur Lesezugriff. Das Hinzufügen von Schreiboperationen (Sitemap einreichen, Indizierung anfordern) wurde bewusst weggelassen – sie sind in einem LLM-Kontext riskant. Öffnen Sie einen PR, wenn Sie sie benötigen.

• Single-Tenant-Design. Ein Betreiber stellt bereit, ein Bearer-Token schützt den Connector, der Zugriff ist an denjenigen gebunden, der den Google OAuth-Vorgang abschließt. Multi-User-SaaS-Stil ist nicht vorgesehen.

• OAuth-Zustimmung im Testmodus begrenzt auf 100 Testbenutzer (für den persönlichen/Team-Einsatz mehr als ausreichend). Für eine breitere Verteilung müssten Sie die App zur Google-Verifizierung einreichen (webmasters.readonly ist ein „sensibler" Bereich, erfordert manuelle Überprüfung).

• GSC-API-Kontingente – 1200 Abfragen/Min./Projekt, 30.000/Tag. Reichlich für den interaktiven Gebrauch.

• Datumsbereich – GSC gibt die letzten 16 Monate zurück. Frühere Daten führen zu Fehlern.

Fehlerbehebung

Technologie

• Cloudflare Workers + Durable Objects (über das agents-SDK ≥0.12)

• @cloudflare/workers-oauth-provider für OAuth 2.1 + DCR + PKCE

• @modelcontextprotocol/sdk für Tool-Definitionen

• KV-Namespace OAUTH_KV für OAuth-Status

• Google OAuth 2.0-Ablauf nativ über Web Crypto API (keine Node-Abhängigkeiten)

Danksagungen

Erstellt von Julien Gourdon – SEO-Berater, der die Schnittstelle zwischen Suche und KI erkundet.

Lizenz

MIT — siehe LICENSE.