GSC-MCP

Remote-MCP-Server, der Google-Search-Console-Daten in Claude, ChatGPT und Cursor verfügbar macht — auf Basis von Googles vollständigem Datenexport statt der limitierten API.

Domain: gsc2mcp.drossmedia.de · Betrieb: netcup Root Server, Nürnberg, mit Cloudflare davor

Status: Die gesamte Anwendung steht als getesteter Code — MCP-Server (JSON- und SSE-Transport), OAuth-Authorization-Server, beide Datenpfade (Lesen und Ingest), Sync-Worker und HTTP-Bootstrap, dazu die Deploy-Artefakte. 253 Tests, davon 34 gegen echtes PostgreSQL. Offen ist nur noch das Anbinden an reale externe Systeme (GCP-OAuth-Client samt Google-Verifizierung, BigQuery-Dienstkonto, Server-Bestellung, Live-DNS). Der Umsetzungsstand (docs/13) hält das PR-übergreifend fest.

Worum es geht

Die Search Console API ist eng begrenzt: 16 Monate Historie, 25.000 Zeilen pro Request, rund 50.000 Zeilen pro Tag und Suchtyp. Ausnahmslos jedes Werkzeug am Markt nutzt diese API — auch die, die Daten anschließend speichern. Sie speichern damit eine Stichprobe.

Googles Bulk Data Export hat keine dieser Grenzen: vollständige Suchdaten, täglich, ohne API-Quote, unbegrenzt aufbewahrbar. Was ihm fehlt, ist alles andere — keine Oberfläche, keine Analyse, kein Agentenzugang.

GSC-MCP schließt genau diese Lücke und ergänzt eine deterministische Analyse-Engine: Change-Attribution, saisonbereinigte Anomalie-Erkennung, site-eigene CTR-Kurven, Kannibalisierungs-Zeitreihen. Die Zahlen sind nachrechenbar, nicht geschätzt.

Wie groß der Unterschied ist, ist gemessen: Bei sc-domain:aip.aero entfallen auf die 100 klickstärksten Suchanfragen 8,3 % der Klicks — rund 92 % des Geschehens liegen außerhalb dessen, was ein Werkzeug mit Zeilendeckel zeigt.

Dokumentation

Dokument	Inhalt
00 — Konzept	Vision, Marktumfeld, Zielgruppen
01 — Architektur	netcup + Cloudflare, Komponenten, Skalierungspfad
02 — Auth	Die zwei OAuth-Ebenen, Google-Verifizierung, Token-Handling
03 — Datenmodell	PostgreSQL-Schema, Partitionierung, Volumenrechnung
04 — Sync-Pipeline	Backfill, Delta-Sync, Quoten-Mathematik, Fehlerverhalten
05 — Tools	Die MCP-Oberfläche: 26 Tools, Schemata, Antwortbudgets
06 — Analyse-Engine	Die Formeln hinter Attribution, Anomalien, CTR-Kurven
07 — Billing	Plan-Matrix, Stripe-Objekte, Entitlements
08 — Sicherheit & DSGVO	Datenresidenz, Verschlüsselung, Löschkonzept
09 — Roadmap	Phasen 0–6, Aufwände, Risiken
10 — Repo-Struktur	Monorepo-Layout, Tooling
11 — Go-to-Market	Connector Directory, Kanäle, Launch
12 — Wettbewerb & USP	Marktscan, ehrliche Prüfung der Differenzierer, Positionierung
13 — Umsetzungsstand	PR-übergreifender Ist-Zustand des Codes, Testtiefe, offene Betreiber-Schritte

Architektur in Kürze

Claude / ChatGPT / Cursor
        │  Streamable HTTP + OAuth 2.1
        ▼
   Cloudflare (TLS, DDoS, WAF, Rate Limiting)
        │
        ▼
   netcup Root Server · Nürnberg
     Caddy → app (MCP + OAuth AS) · web · worker
     PostgreSQL 17 (Warehouse, pg-boss, Rate-Budget)
        │
        ├──▶ Search Console API      (einmaliger 16-Monats-Backfill)
        └──▶ BigQuery Bulk Export    (laufend, vollständig, ohne API-Quote)

Ein zweiter Hostname gsc2mcp-direct.drossmedia.de läuft ohne Cloudflare direkt auf den Server — für Kunden, deren Beschaffung keinen US-Auftragsverarbeiter zulässt, und als Notweg bei einem Proxy-Ausfall.

Projektstruktur

Monorepo, npm-Workspaces, TypeScript strict, Vitest.

Package	Rolle	Status
packages/core	Plan-Matrix, Entitlements, Metrik-Grundregeln	✅ getestet
packages/analytics	Change-Attribution, CTR-Kurve (isoton) — der USP	✅ getestet
packages/db	Drizzle-Modelle, kanonische Migration, Abstimmungs-Helfer	✅ getestet
packages/gsc-client	Search-Console-Client: Pagination, Backoff, Fehlerübersetzung	✅ getestet
apps/app	MCP-Server (JSON + SSE), OAuth-AS, HTTP-Routing, Bootstrap	✅ getestet
apps/worker	Sync: Rate-Limiter, Planer, beide Ingest-Pfade, pg-boss-Konsument	✅ getestet

Die kanonische DDL liegt in packages/db/migrations/0001_init.sql und wird gegen echtes PostgreSQL validiert; docs/03 begründet sie.

Entwicklung

npm install
npm run typecheck   # tsc --build über alle Packages
npm test            # Vitest über packages/*/test und apps/*/test

CI (GitHub Actions) prüft zusätzlich die Migration gegen ein echtes PostgreSQL, die Konzeptdokumente (Links, Konsistenz) und die Übersichtsseite in beiden Themes. Siehe docs/10-repo-struktur.md und CLAUDE.md.

Nächste Schritte

Der kritische Pfad ist nicht der Code, sondern die Google-OAuth-Verifizierung für den sensitiven Scope webmasters.readonly — sie dauert typischerweise mehrere Wochen und setzt Domain und Datenschutzerklärung voraus. Details in docs/02-auth.md und docs/09-roadmap.md.

Vor Phase 2 ist außerdem zu entscheiden, wohin der Bulk Data Export liefert — in das BigQuery-Projekt des Kunden oder in unseres. Die Abwägung steht in docs/12-wettbewerb-usp.md.