Google-Sichtbarkeit mit Claude automatisiert im Blick behalten
Ein Google-Service-Account ist der sauberere Weg, um eigene Skripte oder Claude Code an die Google-Search-Console-API anzubinden, statt einen Drittanbieter-MCP-Server mit interaktivem OAuth-Consent dazwischenzuschalten: kein Consent-Screen, keine fremde Software zwischen dir und deinen eigenen Daten, und der Zugriff lässt sich jederzeit in der Search Console selbst wieder entziehen.
Ich hab dafür ein paar Stunden gebraucht, weil die meisten Tutorials im Netz auf genau diese Drittanbieter-Wrapper setzen und den offiziellen Service-Account-Weg gar nicht erst erwähnen.
Der Ablauf selbst ist, einmal eingerichtet, unspektakulär: Google-Cloud-Projekt anlegen, Search-Console-API aktivieren, einen Service Account erstellen, dessen JSON-Key sicher ablegen und den Service Account als eingeschränkten „Nur-Lese-Nutzer" in der Search Console eintragen.
Danach kann jedes Python-Skript oder jeder Claude-Code-Lauf ganz normal Performance-Daten abfragen, ohne dass irgendwo ein Browser-Consent-Fenster aufpoppt — genau die Grundlage, die es braucht, damit eine KI die Zahlen nicht nur abruft, sondern auch interpretiert. Als Bonus zeig ich, wie ein systemd-User-Timer statt eines klassischen Cron-Jobs verpasste Läufe automatisch nachholt, wenn der Rechner mal aus war.
Den kompletten, getesteten Code gibt's auch als eigenständiges Repo: Pythia.
Service Account vs. OAuth-Consent-MCP
Warum überhaupt der Umweg über einen eigenen Service Account, wenn es fertige MCP-Server für die Search-Console-API gibt? Technisch nutzen beide Wege OAuth 2.0 — der eigentliche Unterschied ist, ob dafür einmalig ein Mensch im Browser zustimmen muss und ob fremder Server-Code dazwischenhängt.
| OAuth-Consent-MCP (Drittanbieter) | Service Account | |
|---|---|---|
| Setup-Aufwand | Gering, einmal durchklicken | Etwas mehr (GCP-Projekt, Service Account, Key) |
| Läuft über gehosteten Drittanbieter-Server | Meistens ja | Nein |
| Braucht einmalig interaktiven Consent im Browser | Ja, beim ersten Login | Nie |
| Geeignet für unbeaufsichtigte Automatisierung (Cron/Timer) | Mit sicher gespeichertem Refresh-Token möglich | Ja, ganz ohne Consent-Schritt |
| Zugriff granular widerrufbar | Über Drittanbieter-Einstellungen | Direkt in der Search Console |
Für eine einmalige, interaktive Abfrage reicht ein OAuth-Consent-MCP locker — auch für wiederkehrende Läufe geht das grundsätzlich, wenn man sich um einen sicher gespeicherten Refresh-Token kümmert. Der Service Account nimmt einem genau diese Fürsorge ab: kein Token-Handling, kein fremder Server, kein Consent-Schritt, der im Weg stehen könnte.
Bevor du anfängst
- Ein Google-Cloud-Konto (kostenlos)
- Eine Property in der Google Search Console, auf die du Zugriff hast
- Python 3 mit
venv - 15-20 Minuten für die einmalige Einrichtung
Einrichtung
1. Google-Cloud-Projekt anlegen und Search Console API aktivieren
In der Google Cloud Console ein neues Projekt anlegen (z. B. <projekt>-search-console), dann unter "APIs & Services" → "Library" nach "Google Search Console API" suchen und aktivieren.
Stolperstein: Google Cloud merkt sich das zuletzt aktive Projekt. Es ist leicht, versehentlich im falschen (z. B. einem älteren) Projekt zu landen — vor dem Aktivieren immer oben in der Projekt-Auswahl kontrollieren, in welchem Projekt du gerade bist.
2. Service Account anlegen
Im linken Menü der Google Cloud Console auf "IAM and admin" klicken — das öffnet ein Untermenü, dort "Service Accounts" auswählen. Dann "Create Service Account", Name vergeben, fertig — die optionalen Schritte "Grant this service account access to project" und "Grant users access to this service account" bewusst überspringen, die brauchen wir für unseren Zweck nicht.
Stolperstein: Browser-Zurück-Taste während dieses Assistenten erzeugt gerne doppelte Service Accounts. Lieber neu von "Create Service Account" starten, statt mit Zurück zu navigieren.
3. JSON-Key erzeugen und sicher ablegen
Im angelegten Service Account → Tab "Keys" → "Add Key" → "Create new key" → JSON.
Google warnt an dieser Stelle selbst davor, dass Service-Account-Keys ein Sicherheitsrisiko sind — und das Expiry-Datum oben zeigt auch warum: JSON-Keys laufen standardmäßig nie ab. Ohne eine explizite Google-Cloud-Organisationsrichtlinie, die eine Ablaufzeit erzwingt, bleibt so ein Key auf unbestimmte Zeit gültig. Wer den Weg aus diesem Artikel nutzt, sollte sich das als wiederkehrende Aufgabe vormerken: nicht mehr gebrauchte Keys im "Keys"-Tab aktiv löschen, statt sie einfach liegen zu lassen.
Die heruntergeladene Datei niemals in ein Git-Repo legen. Stattdessen z. B.:
mkdir -p ~/.config/<projekt>
mv ~/Downloads/<projekt>-xxxxx.json ~/.config/<projekt>/service-account.json
chmod 600 ~/.config/<projekt>/service-account.json
Falls der Key mal in der Nähe eines Git-Repos landen soll (z. B. weil ein Skript ihn im selben Ordner erwartet): lieber dorthin symlinken statt kopieren. Ein .gitignore-Eintrag schützt einen Symlink genauso wie eine echte Datei — aber selbst im Worst Case eines erzwungenen git add -f speichert Git bei einem Symlink nur den Ziel-Pfad als Text, nie den tatsächlichen Dateiinhalt. Ein versehentlicher Force-Add würde dann höchstens einen lokalen Pfad verraten, nicht den Key selbst. Genau so ist es im Pythia-Repo gelöst.
4. Service Account in der Search Console eintragen
In der Search Console der gewünschten Property → "Einstellungen" → "Nutzer und Berechtigungen" → "Nutzer hinzufügen". Die E-Mail-Adresse des Service Accounts (endet auf @<projekt>.iam.gserviceaccount.com) eintragen, Berechtigung "Eingeschränkt" (read-only) reicht für Auswertungen völlig aus.
Stolperstein: Domain-Property vs. URL-Präfix-Property. Eine Domain-Property (sc-domain:example.com) aggregiert automatisch alle Subdomains — wenn du z. B. ein separates Hobby-/Nebenprojekt auf einer Subdomain hast, landen dessen Daten ungewollt mit im selben Bericht. Für saubere Auswertungen lieber eine eigene URL-Präfix-Property für genau die Property anlegen, die du auswerten willst.
Erste Abfrage
Python-Umgebung einrichten:
python3 -m venv ~/.config/<projekt>/venv
~/.config/<projekt>/venv/bin/pip install google-auth google-api-python-client
Das Skript erwartet service-account.json im selben Ordner wie sich selbst — leg beides also zusammen in ~/.config/<projekt>/ ab. Den vollständigen, getesteten Code gibt's hier statt zum Abtippen (Einrückung geht bei Copy-Paste aus einer Webseite erfahrungsgemäß gern kaputt):
Er prüft Eingaben (ungültige Tage/Limits/Dimensionen) und fängt die häufigsten Fehlerfälle mit einer klaren Meldung statt eines rohen Python-Tracebacks ab: fehlende Abhängigkeiten, fehlender Key, 403 bei falscher Property-Berechtigung oder nicht existenter Property, 400 bei ungültiger Property-Syntax.
Aufruf (aus dem ~/.config/<projekt>/-Ordner heraus, oder mit vollem Pfad zu query.py):
~/.config/<projekt>/venv/bin/python ~/.config/<projekt>/query.py "https://www.example.com/" --days 7 --dimensions page --limit 25Kein Browser-Fenster, kein Consent-Dialog — die Authentifizierung läuft komplett über den Service-Account-Key.
Warum nicht einfach in der Search Console nachschauen?
Berechtigte Frage an dieser Stelle: Die Zahlen stehen doch alle schon im Browser, wozu der ganze API-Aufwand? Wenn es nur ums Anschauen ginge — zu Recht keiner.
Der Punkt ist, was hinter der API passiert, sobald man sie an Claude Code statt an ein Dashboard hängt. 2026 ist es nicht mehr nötig, sich selbst jede Woche durch dieselben Tabellen zu klicken und im Kopf mit der Vorwoche zu vergleichen — das kann ein LLM übernehmen, und zwar nicht nur als Zahlenfilter, sondern als Analysewerkzeug, das die Zahlen tatsächlich einordnet: Was hat sich seit letzter Woche verändert, welche Seite verliert trotz guter Position plötzlich Klicks, wo lohnt sich ein Blick auf Title und Meta Description, weil die Suchbegriffe nicht mehr zum Text passen. Das Ergebnis ist kein Datenexport, sondern ein fertig eingeordneter Bericht mit konkreten Handlungsvorschlägen — genau das übernimmt der Prompt im verlinkten weekly-report.sh.
Wiederkehrender Check: systemd-User-Timer statt Cron
Für einen wöchentlichen Report ist ein systemd-User-Timer einem klassischen Cron-Job vorzuziehen, weil er verpasste Läufe automatisch nachholt (Persistent=true) — praktisch, wenn der Rechner am geplanten Zeitpunkt mal aus oder im Standby war, was bei einem normalen Desktop/Laptop öfter vorkommt als bei einem Server.
Skript und beide Unit-Dateien, fertig zum Klonen und mit Kommentaren, wo genau SITE_URL und der Pfad zu weekly-report.sh reinmüssen:
Nach ~/.config/systemd/user/ kopieren und aktivieren:
systemctl --user daemon-reload
systemctl --user enable --now search-console-weekly.timerMit systemctl --user list-timers prüfen, wann der nächste Lauf ansteht.
Stolperstein, den ich beim Zusammenbauen für den öffentlichen Code selbst gemacht habe: Das erste Skript hat den Pfad zu sich selbst und zum venv fest verdrahtet (~/.config/google-search-console/...). Funktioniert lokal, bricht aber sofort, sobald jemand anderes das Repo an eine andere Stelle klont. Die robustere Lösung: Das Skript ermittelt sein eigenes Verzeichnis zur Laufzeit (dirname "$(readlink -f "$0")") und baut alle Pfade relativ dazu auf. Kein Problem, wenn man von Anfang an nur für sich selbst schreibt — wird aber sofort zum Bug, sobald der Code weitergegeben werden soll. Genau das ist in den drei Dateien oben schon eingebaut.
Fehlerbehebung
- PERMISSION_DENIED bei der Abfrage: Service Account wurde nicht (oder mit falscher E-Mail-Adresse) als Nutzer in der Search-Console-Property eingetragen — Schritt 4 prüfen.
- Falsche/leere Daten: Property-Typ prüfen — Domain-Property aggregiert Subdomains mit rein, URL-Präfix-Property nicht. Ggf. die falsche Property abgefragt.
- API nicht aktiviert: Fehlermeldung nennt meist direkt den Google-Cloud-Projektnamen — prüfen, ob das wirklich das Projekt ist, in dem die Search Console API aktiviert wurde (siehe Stolperstein oben).
- Timer läuft nicht:
systemctl --user status search-console-weekly.timerundjournalctl --user -u search-console-weekly.serviceprüfen. Bei manchen Distros muss "linger" aktiviert sein (loginctl enable-linger $USER), damit User-Timer auch ohne aktive Anmeldesitzung laufen.
Fazit
Für eine einmalige, interaktive Abfrage ist ein fertiger OAuth-Consent-MCP-Server die schnellere Wahl. Sobald ein Skript aber regelmäßig und unbeaufsichtigt laufen soll — täglich, wöchentlich, per Timer statt manuell angestoßen — ist der Service-Account-Weg der robustere: kein Consent-Dialog, der plötzlich mitten in einem automatisierten Lauf auftaucht, und der Zugriff bleibt jederzeit direkt in der Search Console kontrollierbar.
Die API liefert nur die Daten; den praktischen Wert schafft der automatisierte Bericht, der Veränderungen einordnet und daraus konkrete nächste Schritte ableitet.
Den kompletten Code aus diesem Artikel — query.py mit Fehlerbehandlung, weekly-report.sh, beide systemd-Units, README für Einsteiger — gibt's fertig zum Klonen unter github.com/Agundur-KDE/Pythia.
