seo-analytics-mcp

Google Search Console, GA4 und IndexNow — als MCP-Server.

Frag Claude nach deinen eigenen Websites. Was rankt, was sich geändert hat, was indexiert ist, was konvertiert.

"Which pages lost the most clicks in the last 28 days versus the 28 before?"
"How is /pricing doing?"
"Is https://example.com/new-post indexed yet?"
"Which pages rank on page one but get almost no clicks?"
"Top 20 queries for the blog last month, and which of them convert in GA4."

Du autorisierst dein eigenes Google-Konto gegen einen OAuth-Client in deinem eigenen Google-Cloud-Projekt. Nichts an deinem Zugriff läuft über jemand anderen, dieses Repository enthält keine Zugangsdaten, und jedes Google-Kontingent, das du verbrauchst, ist dein eigenes.

Inhalt

Installation · Einrichtung · Das Sieben-Tage-Problem · Tools · Antwortformat · Konfiguration · Schreibzugriffe · Profile · Design · Fehlerbehebung · Entwicklung

Related MCP server: GSC Analyst Connector

Installation

Erfordert Python 3.10+ und uv.

uvx seo-analytics-mcp doctor      # no install needed — prints your setup steps, in order

doctor ist das gesamte Onboarding-Erlebnis. Es sagt dir in jeder Phase genau, was fehlt und was du als Nächstes ausführen sollst. Wenn du hier sonst nichts liest, führe das aus.

Einrichtung

Sechs Klicks in der Google-Cloud-Konsole, dann ein Befehl. Zehn Minuten, einmalig.

Erstelle ein Google-Cloud-Projekt — oder verwende ein bestehendes. console.cloud.google.com/projectcreate

Aktiviere die APIs. Search Console ist erforderlich; das GA4-Paar ist optional.

searchconsole · analyticsdata · analyticsadmin

Konfiguriere den Zustimmungsbildschirm und klicke dann auf App veröffentlichen. console.cloud.google.com/auth/overview

Wähle Extern und veröffentliche. Du bist der einzige Nutzer deiner eigenen App, daher gilt die Ausnahme für den persönlichen Gebrauch von Google und es ist keine Verifizierung erforderlich. Workspace-Nutzer können stattdessen Intern wählen.

Überspringe den Schritt Veröffentlichen nicht — siehe unten.

Erstelle einen OAuth-Client vom Typ Desktop app und lade das JSON herunter. console.cloud.google.com/auth/clients

Ein Webanwendungs-Client kann die Loopback-Weiterleitung, die dieser Server benötigt, nicht durchführen. doctor prüft auf genau diesen Fehler, weil er leicht zu machen ist.

Autorisiere einmalig von einem Terminal aus:

uvx seo-analytics-mcp auth --client-secret ~/Downloads/client_secret_*.json

Dein Browser öffnet sich. Google sagt „Google hat diese App nicht verifiziert" — erwartbar für deinen eigenen Client: Erweitert → Weiter. Das Token landet in deinem Profilverzeichnis mit der Berechtigung 0600.

Prüfe und verbinde dann:

uvx seo-analytics-mcp doctor      # eleven checks; exit 0 means it will work

Verbinden

claude mcp add seo \
  -e GSC_DEFAULT_SITE=sc-domain:example.com \
  -e GA4_DEFAULT_PROPERTY=properties/123456789 \
  -- uvx seo-analytics-mcp

{
  "mcpServers": {
    "seo": {
      "command": "uvx",
      "args": ["seo-analytics-mcp"],
      "env": {
        "GSC_DEFAULT_SITE": "sc-domain:example.com",
        "GA4_DEFAULT_PROPERTY": "properties/123456789"
      }
    }
  }
}

Beende dann Claude Desktop vollständig (⌘Q — das Schließen des Fensters reicht nicht) und öffne es erneut.

[!HINWEIS] In dieser Konfiguration gibt es keinen Pfad zu Zugangsdaten. Das Token liegt im Profilverzeichnis, das seo-mcp auth geschrieben hat, daher kann der gesamte Block bedenkenlos in ein GitHub-Issue eingefügt werden.

Das Sieben-Tage-Problem

[!WARNUNG] Wenn der Server funktioniert und etwa eine Woche später aufhört, ist das der Grund.

Google stellt Refresh-Tokens aus, die nach sieben Tagen ablaufen für jede externe OAuth-App, deren Veröffentlichungsstatus noch Test ist. Der naheliegende Einrichtungsweg — Projekt erstellen, Client erstellen, sich selbst als Testnutzer hinzufügen — lässt dich dort zurück.

Die Lösung ist ein Klick: Setze auf dem Zustimmungsbildschirm die Zielgruppe auf Extern und klicke auf App veröffentlichen. Dann uvx seo-analytics-mcp auth --reauth.

doctor markiert ein Token, das jung genug ist, um noch ein Test-Token zu sein, und jeder invalid_grant-Fehler vom Server erklärt das ausführlich. Es ist kein Bug im Server — aber es wird das am häufigsten gemeldete Problem sein.

Tools

Dreizehn Tools: zehn bilden Upstream-Operationen ab, zwei verbinden Quellen, und eines existiert nur, damit das Modell einem verwirrten Nutzer sagen kann, was zu tun ist.

Wie eine Antwort aussieht

Jedes Lesetool gibt dieselben vier Schlüssel zurück. Begrenzt, selbsterklärend und mit eigenen Einschränkungen versehen.

{
  "summary": {
    "source": "gsc",
    "rows_returned": 10,        // what you see
    "rows_matched": 1847,       // what exists upstream
    "date_range": "2026-07-29..2026-08-25",   // resolved, always echoed
    "data_state": "final",
    "totals": { "clicks": 4730, "impressions": 512903, "ctr": 0.0092, "position": 12.4 }
  },
  "rows": [ /* capped at min(row_limit, 1000) */ ],
  "notes": [
    "Google anonymises rare queries: these rows do NOT sum to property totals.",
    "dataState=final excludes the most recent 2-3 days.",
    "1837 further rows were not included inline."
  ],
  "export": "~/.../exports/a1b2c3.csv"        // only when rows spilled
}

Drei Konventionen gelten überall:

Summen decken alle abgerufenen Zeilen ab, nicht nur die angezeigten — ein Modell, das zehn Zeilen und eine Summe für zehn sieht, kann Kürzung nicht von Realität unterscheiden. Raten werden nie gemittelt: ctr wird neu berechnet aus Klicks ÷ Impressionen, position ist impressionsgewichtet, engagementRate ist Engagement ÷ Sitzungen.

Einschränkungen reisen mit den Daten. Die Ebene, die die Einschränkung kennt, fügt sie hinzu: Der Client weiß, dass die query-Dimension angefordert wurde, shape() weiß, wie viele Zeilen es verworfen hat, GA4 weiß, dass die Antwort gesampelt wurde. Docstrings allein verlieren sie genau dann, wenn das Modell auf die Zahlen schaut.

Fehler benennen die Lösung. Ein 403 sagt dir, welche Berechtigung du prüfen und wo — niemals ein roher Google-Fehlertext.

The authorised Google account has no access to sc-domain:example.com. Confirm the
account you authorised is the one with access — Search Console grants are per-property
under Settings > Users and permissions, GA4 grants are per-property under Admin >
Property access management. If access was added recently, run `seo-mcp auth --reauth`.

Konfiguration

Jede Variable ist optional. Priorität: Tool-Argument → Umgebung → Profil-config.json.

Daten

Jedes Datumsargument akzeptiert YYYY-MM-DD, today, yesterday oder NdaysAgo. Antworten geben den absoluten Bereich zurück, den sie tatsächlich verwendet haben, denn ein Modell, das das heutige Datum falsch errät, erzeugt ein leeres Ergebnis, das wie „Der Traffic ist auf null gefallen" wirkt.

Search Console hinkt 2–3 Tage hinterher und behält ~16 Monate; Bereiche außerhalb dieser Grenzen werden markiert oder abgelehnt, statt stillschweigend nichts zurückzugeben. GA4 berichtet in der eigenen Zeitzone der Property, daher stimmen die Daten nicht exakt mit denen der Search Console überein — die Antworten sagen das dort, wo es relevant ist.

Schreibzugriffe

Zwei Tools wirken auf die Welt außerhalb deines Rechners. Beide sind absichtlich umständlich.

[!WICHTIG] Ein confirm-Flag allein ist kein Sicherheitsmechanismus — es ist ein Argument, das das Modell ausfüllt, und dieselbe Fehlinterpretation, die die falschen URLs erzeugt, erzeugt confirm=true daneben.

Das Token ist ohne Trockenlauf nicht fälschbar, und ändere eine URL, und es passt nicht mehr. Beide Tools tragen außerdem destructiveHint-Annotationen, sodass ein Client, der destruktive Tools hinter einer eigenen Genehmigungsabfrage absichert, dies tun wird.

Schreibgeschützte Bereiche sind die Standardeinstellung. Ein Fremder, der ein SEO-Tool installiert, das sofort um Erlaubnis bittet, seine Search-Console-Properties zu ändern, wird das zu Recht ablehnen.

Profile

Mehrere Google-Konten auf einem Rechner — für Agenturen, die Kunden-Properties nebeneinander verwalten.

uvx seo-analytics-mcp auth --profile client-a --client-secret ./client-a.json
uvx seo-analytics-mcp auth --profile client-b --client-secret ./client-b.json
uvx seo-analytics-mcp profiles list

Setze SEO_MCP_PROFILE pro MCP-Servereintrag. Cache-Schlüssel enthalten das Profil, sodass zwei Konten niemals gegenseitig ihre Daten ausliefern können.

Ein Profil ist ein Verzeichnis — das Erste, das du einen Nutzer je zu löschen bitten wirst:

uvx seo-analytics-mcp profiles rm client-a --yes

Sie liegen in ~/Library/Application Support/seo-mcp/ (macOS), $XDG_CONFIG_HOME/seo-mcp/ (Linux) oder %APPDATA%\seo-mcp\ (Windows).

Design

Vier Ebenen, strikt abwärts. Wenn du das falsch machst, landet der Auth-Fluss in einem Tool-Aufruf, was der Fehler ist, den das gesamte Design verhindern soll.

flowchart TD
    subgraph L4["Entry points"]
        S[server.py<br/><i>MCPServer, stdio</i>]
        C[cli.py<br/><i>auth · doctor · profiles · serve</i>]
    end
    subgraph L3["Tools — argument surface, docstrings, cache policy"]
        T[13 handlers<br/><i>no HTTP, no credentials, no row shaping</i>]
    end
    subgraph L2["Clients — the only modules that speak HTTP"]
        G[gsc.py]
        A[ga4.py]
        I[indexnow.py]
    end
    subgraph L1["Leaves — importable by anyone, import nobody"]
        LV[shaping · errors · config · cache · auth/store · auth/scopes]
    end
    F[auth/flow.py<br/><i>loopback + PKCE · opens a browser</i>]

    S --> T
    C --> T
    C -.->|only reachable from here| F
    T --> G & A & I
    G & A & I --> LV

Der Browser-Fluss darf niemals in einem Tool-Aufruf laufen. Ein MCP-Tool, das auf stdio blockiert und auf einen Menschen wartet, der einen Zustimmungsbildschirm abschließt, sieht wie ein hängender Server aus, und das Modell kann nicht helfen. Ein CLI-Befehl, einmal ausgeführt, ist der ganze Unterschied — und ein Test durchläuft den AST jedes Moduls, um das durchzusetzen.

Andere Regeln, die die Tests mechanisch durchsetzen: shaping.py importiert keine Google-Bibliothek (weshalb die Zeilenlogik ohne Zugangsdaten vollständig unit-testbar ist), Tools importieren keine HTTP-Bibliothek, und nichts auf dem Serverpfad ruft print() auf — bei einem stdio-Transport trägt stdout JSON-RPC, und ein einziger verirrter print korrumpiert den Stream.

Fehlerbehebung

Jeder Problembericht sollte seo-mcp doctor --json enthalten. Es enthält keine Anmeldeinformationen – nur Pfade, Versionen, welche Prüfungen bestanden wurden und welche APIs geantwortet haben.

Entwicklung

uv sync --extra dev
uv run pytest -q                    # 147 tests · no credentials · no network
uv run python scripts/smoke.py      # drives the server over real stdio JSON-RPC
uv run ruff check src tests

python3 -m venv .venv && ./.venv/bin/pip install -e ".[dev]"
./.venv/bin/python -m pytest -q
./.venv/bin/python scripts/smoke.py ./.venv/bin/seo-mcp

scripts/smoke.py startet den Server als Unterprozess, führt den MCP-Handshake durch, listet die Tools auf und ruft mehrere auf – unter Verwendung eines Wegwerf-Profilverzeichnisses, sodass dein echtes Token unberührt bleibt. Es ist der schnellste Weg, um zu bestätigen, dass die Protokollseite funktioniert, bevor irgendeine Google-Anmeldeinformation existiert.

Um manuell daran herumzutesten, benötigt der MCP Inspector nichts weiter als Node:

npx @modelcontextprotocol/inspector ./.venv/bin/seo-mcp            # web UI
npx @modelcontextprotocol/inspector --cli ./.venv/bin/seo-mcp \
    --method tools/call --tool-name auth_status                    # scriptable

Nicht von automatisierten Tests abgedeckt: der OAuth-Ablauf selbst und die Live-IndexNow-Übermittlung. Beide benötigen einen Menschen und eine echte Domain, und das Mocken würde nur den Mock testen. Sie gehören in eine kurze manuelle Release-Checkliste.

Zwei Dinge, die es nicht tun wird

[!NOTE] IndexNow erreicht Google nicht. Teilnehmer sind Bing, Yandex, Naver, Seznam.cz, Yep und Amazon – ein Endpunkt propagiert an alle. Google nimmt nicht teil, und Googles eigene Indexing-API akzeptiert nur Seiten mit JobPosting- oder BroadcastEvent-Strukturdaten. Wenn du dies installierst, um eine schnellere Google-Indizierung zu erwarten, wirst du enttäuscht sein.

[!NOTE] Abfragezeilen summieren sich nie zu Gesamtsummen. Google anonymisiert seltene Abfragen, daher unterschätzt jede Aufschlüsselung nach der query-Dimension. Jede Antwort, die diese Dimension enthält, wiederholt den Hinweis, weil ein Modell, dem diese Zeilen übergeben werden, sonst selbstbewusst falsche Prozentsätze berechnet.

Mitwirken

Issues und Pull-Requests sind willkommen. Die anmeldefreie Testsuite läuft bei jedem Push auf Linux, macOS und Windows mit Python 3.10 und 3.13 – wenn sie lokal besteht, besteht sie auch in CI.

Das Umbenennen eines Tools oder das Ändern eines Arguments bricht jeden gespeicherten Prompt, den ein Benutzer hat. Diese Änderungen gehen in CHANGELOG.md und sind vor 1.0 ein Minor-Bump, danach ein Major-Bump.

Lizenz

MIT.