gsc-mcp-connector

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

Was Sie damit erhalten

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

• list_sites – entdecken Sie jede Property, auf die der authentifizierte Benutzer zugreifen kann

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

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

• list_sitemaps – jede eingereichte Sitemap und deren Verarbeitungsstatus

Sie fragen: "Quelles sont mes 50 requêtes avec la plus grosse perte de clics entre les 28 derniers jours et les 28 jours précédents ?" und der Assistent zieht die Daten, berechnet die Differenz und schreibt die Analyse. Keine SQL-Exporte 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 Anmeldeoberfläche fragt nach einem statischen „Access Key", den Sie bei der Bereitstellung festlegen (das Connector-Gate).

2. Worker → Google: Nach der Überprüfung des Access Keys wird der Benutzer zum Google-Zustimmungsbildschirm weitergeleitet, um webmasters.readonly zu gewähren. Das resultierende Refresh-Token wird im OAuth-Grant gespeichert; bei jedem Tool-Aufruf frischt der Worker ein neues Access-Token auf und ruft die GSC auf.

Das Google-Konto des Benutzers steuert den Zugriff – kein Service Account, kein GSC-Benutzerverwaltungs-Tanz, keine Verzögerungen bei der Berechtigungsweitergabe.

Voraussetzungen

Die kostenlose Stufe von Cloudflare Workers (100.000 Anfragen/Tag) ist für den persönlichen SEO-Einsatz völlig ausreichend. Kein kostenpflichtiger Cloudflare-Plan erforderlich.

Schnellstart (~15 Min.)

1. Worker bereitstellen

Klicken Sie auf den Deploy to Cloudflare-Button oben in dieser README. 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 dieser Phase werden Sie nach MCP_BEARER_TOKEN, GOOGLE_OAUTH_CLIENT_ID und GOOGLE_OAUTH_CLIENT_SECRET gefragt. Sie haben die Google-Daten 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 setzen sie in Schritt 4 richtig.

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 sich nach der Bereitstellung Ihre Worker-URL. Sie benötigen sie sowohl in Schritt 3 als auch in Schritt 5.

2. Einen Connector-Access-Key generieren

Dies ist ein statischer zufälliger String, der als Gate vor Google OAuth dient. Jeder, der den Connector verwendet, muss diesen String in der Anmeldeoberfläche einfügen.

openssl rand -hex 32

Speichern Sie die Ausgabe – Sie werden sie als Secret setzen 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 im Authorized redirect URI. Sie erhalten eine Client ID und ein Client Secret.

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

4. Worker-Secrets 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 – Kodierungsfalle unter Windows: Wenn Sie den Inhalt einer Datei weiterleiten (z.B. Get-Content | wrangler secret put) und diese Datei ein UTF-8-BOM enthält, landet das BOM in Ihrem Secret und zerstört das JSON-Parsing. Das Cloudflare-Dashboard oder das interaktive wrangler secret put (Einfügen an der 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

• „I understand and want to continue" aktivieren

• Create

Ein Popup öffnet sich zur Anmeldeoberfläche Ihres Workers. Fügen Sie Ihren MCP_BEARER_TOKEN ein → klicken Sie Continue with Google → → Google fordert Sie auf, sich anzumelden (verwenden Sie das Konto, dem Ihre GSC-Property gehört) und webmasters.readonly zu gewähren → 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: „List my Google Search Console sites". Sie sollten Ihre Properties 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-Fluss nicht vollständig abschließen kann, da die Weiterleitungs-URIs von Google HTTPS erfordern. Für einen echten End-to-End-Test stellen Sie auf Cloudflare bereit und testen Sie gegen die workers.dev-URL.

Einschränkungen

• Nur-Lesen. Schreiboperationen (Sitemap einreichen, Indexierung anfordern) wurden bewusst ausgelassen – sie sind im LLM-Kontext riskant. Öffnen Sie einen Pull-Request, wenn Sie sie benötigen.

• Einzelmandantenfähig von Grund auf. Ein Betreiber stellt bereit, ein Bearer-Token schützt den Connector, der Zugriff ist an denjenigen gebunden, der den Google-OAuth-Tanz abschließt. Multi-User-SaaS-ähnlich ist nicht vorgesehen.

• OAuth-Zustimmung im Testing-Modus begrenzt Sie auf 100 Testnutzer (für den persönlichen/Team-Einsatz völlig 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. Für interaktive Nutzung reichlich.

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

Fehlerbehebung

Technologie-Stack

• Cloudflare Workers + Durable Objects (über 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-Zustand

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

Danksagungen

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

Lizenz

MIT – siehe LICENSE