gsc-ga4-mcp

Ein kleiner lokaler MCP-Server, der Claude Code schreibgeschützten Zugriff auf Google Search Console und GA4 gibt, dazu ein paar Tools, die die beiden Datensätze miteinander verknüpfen.

Das Problem

SEO-Arbeit in einem KI-Assistenten bedeutet normalerweise: CSVs aus der Search Console exportieren, weitere CSVs aus GA4 exportieren, beide in einen Chat einfügen – und das bei jeder neuen Zahl wiederholen. Die beiden Datensätze passen außerdem nie von selbst zusammen: Die Search Console kennt Impressionen, Klicks und CTR; GA4 kennt Sessions, Engagement und Conversions. Die Frage „Welche Seiten bekommen Traffic, verschwenden ihn aber?“ zu beantworten, bedeutet, sie manuell über die URL zu verknüpfen.

Google veröffentlicht einen offiziellen MCP-Server für Analytics, aber er deckt die Search Console nicht ab. Es gibt Community-Server für die Search Console; aber wenn die Daten zu Kunden gehören, ist ein kleiner Wrapper, den man vollständig selbst nachvollziehen kann, besser, als einer fremden Lösung zu vertrauen.

Dieser Server ruft die offiziellen Google-APIs direkt von der eigenen Maschine aus auf – mit schreibgeschützten Scopes.

Related MCP server: Google Search Console MCP Server

Was er kann

Zwanzig MCP-Tools über stdio.

Search Console

GA4

Kombinierte Analyse

Konfiguration

project_mappings und project_lookup lesen eine lokale Datei, die einen Projekt- oder Kundennamen auf die zugehörige GSC-Property und GA4-Property abbildet. So kannst du sagen „Vergleiche GSC und GA4 für example.com“, statt properties/123456789 im Kopf zu haben.

Stack

Node.js + TypeScript. @modelcontextprotocol/sdk für den Server, google-auth-library für die Authentifizierung, zod für die Tool-Schemas. Keine Datenbank, kein gehostetes Backend, keine Telemetrie – der Prozess läuft lokal und Claude Code startet ihn über stdio.

Die Scopes sind schreibgeschützt, und das ist die gesamte Berechtigungsfläche:

• https://www.googleapis.com/auth/webmasters.readonly

• https://www.googleapis.com/auth/analytics.readonly

Die Zugangsdaten liegen außerhalb des Repos, standardmäßig in ~/.config/gsc-ga4-mcp/.

Einrichtung

1. Installation

git clone https://github.com/YOUR_USER/gsc-ga4-mcp.git
cd gsc-ga4-mcp
npm install
npm run build
mkdir -p ~/.config/gsc-ga4-mcp

2. APIs aktivieren

Öffne die Google Cloud Console, erstelle oder wähle ein Projekt und aktiviere dann:

• Google Search Console API

• Google Analytics Data API

• Google Analytics Admin API

3. OAuth-Zugangsdaten erstellen

Unter APIs & Dienste → OAuth-Zustimmungsbildschirm konfigurierst du den Zustimmungsbildschirm. Wähle Extern, wenn die Properties, die du verwaltest, nicht alle in einem einzigen Google Workspace liegen, und füge deine eigene E-Mail-Adresse als Testbenutzer hinzu, solange die App nur für Tests freigegeben ist.

Unter APIs & Dienste → Anmeldedaten erstellst du eine OAuth-Client-ID vom Typ Desktop-App, lädst die JSON-Datei herunter und speicherst sie als ~/.config/gsc-ga4-mcp/oauth-client.json.

Wenn du bei Kundenprojekten die Berechtigungen pro Konto isolieren möchtest, verwende stattdessen ein Dienstkonto und gib seine E-Mail-Adresse mit Lesezugriff auf jede GSC- und GA4-Property. Setze GOOGLE_AUTH_MODE=service_account und sag GOOGLE_SERVICE_ACCOUNT_KEY_FILE auf die Schlüsseldatei.

4. Konfigurieren

cp .env.example .env
cp projects.example.json ~/.config/gsc-ga4-mcp/projects.json

Pfade in .env müssen absolut sein – ~ wird nicht erweitert.

GOOGLE_AUTH_MODE=oauth
GOOGLE_OAUTH_CREDENTIALS_FILE=/Users/YOUR_USER/.config/gsc-ga4-mcp/oauth-client.json
GOOGLE_TOKEN_PATH=/Users/YOUR_USER/.config/gsc-ga4-mcp/token.json
GOOGLE_OAUTH_REDIRECT_URI=http://127.0.0.1:3000/oauth2callback
PROJECTS_CONFIG=/Users/YOUR_USER/.config/gsc-ga4-mcp/projects.json
MCP_DEFAULT_GSC_SITE=sc-domain:example.com
MCP_DEFAULT_GA4_PROPERTY=properties/123456789
MAX_ROWS=25000

Projektzuordnungen (projects.json):

{
  "projects": [
    {
      "name": "My Site",
      "client": "Internal",
      "domain": "example.com",
      "gscSiteUrl": "sc-domain:example.com",
      "ga4Property": "properties/123456789",
      "notes": "Replace with the real GA4 property ID."
    }
  ]
}

5. Autorisieren

npm run auth

Das Skript startet einen Loopback-Listener auf 127.0.0.1:3000 und gibt eine Google-URL aus. Öffne sie, stimme den schreibgeschützten Zugriffsberechtigungen zu und der Token wird über die Variable GOOGLE_TOKEN_PATH geschrieben.

6. In Claude Code registrieren

claude mcp add google-seo -- node /ABSOLUTE/PATH/TO/gsc-ga4-mcp/dist/index.js
claude mcp list

Oder nimm eine .mcp.json in das Projekt auf, in dem die Tools verfügbar sein sollen (siehe .mcp.example.json):

{
  "mcpServers": {
    "google-seo": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/gsc-ga4-mcp/dist/index.js"],
      "env": {
        "GOOGLE_AUTH_MODE": "oauth",
        "GOOGLE_OAUTH_CREDENTIALS_FILE": "/Users/YOUR_USER/.config/gsc-ga4-mcp/oauth-client.json",
        "GOOGLE_TOKEN_PATH": "/Users/YOUR_USER/.config/gsc-ga4-mcp/token.json",
        "PROJECTS_CONFIG": "/Users/YOUR_USER/.config/gsc-ga4-mcp/projects.json",
        "MCP_DEFAULT_GSC_SITE": "sc-domain:example.com",
        "MCP_DEFAULT_GA4_PROPERTY": "properties/123456789"
      }
    }
  }
}

Nutze die CLI-Registrierung, wenn du Pfade und Property-Standards lieber nicht im Repository haben möchtest.

Nutzung mit Claude Code

Stelle deine Anfrage in einfach Anspruchssprache; Claude wählt die passenden Tools aus.

Use gsc_list_sites and ga4_list_properties. Give me a table of the GSC sites
and GA4 properties I can reach.

Analyse organic traffic for sc-domain:example.com over the last 90 days using
gsc_top_queries and gsc_top_pages.

Cross GSC and GA4 for example.com over the last 90 days. Find pages with high
impressions and low CTR, and rank the opportunities by likely impact.

Run seo_opportunity_report and group the output into quick wins, pages that
need a rewrite, and pages that miss search intent.

Inspect https://www.example.com/page/ with gsc_url_inspection and tell me
whether Google has it indexed.

Betriebshinweise

• Halte .env, token.json, projects.json und alle Dienstkontoschlüssel aus der Verskontrolle heraus. Das mitgelieferte .gitignore berücksichtigt sie bereits.

• So um Blog. Zwar nicht ausführlich.

• Widerrufe den Token oder das Dienstkonto, wenn eine Zusammenarbeit endet.

• MAX_ROWS deckelt die Antwortgröße. Senke den Wert, wenn Antworten unhandlich werden.

Fehlerbehebung

• Claude Code erkennt die Tools nicht. Führe claude mcp list aus und danach /mcp in Claude Code aus.

• OAuth-Token-Fehler. Führe npm run auth erneut aus und stelle sicher, dass GOOGLE_TOKEN_PATH ein absoluter Pfad ist.

• access_denied. Füge deine E-Mail-Adresse als Testbenutzer auf dem OAuth-Zustimmungsbildschirm hinzu, solange die App im Testmodus ist.

• Eine Domain fehlt in der Search Console. Die Zugangsdaten benötigen Zugriff auf genau diese Property – sc-domain:example.com und https://www.example.com/ sind verschiedene Properties.

• Eine GA4-Property fehlt. Der Benutzer oder das Dienstkonto ist mindestens ein Viewer auf Konto- oder Property-Ebene nötig.

• gsc_url_inspection schlägt fehl. inspectionUrl muss innerhalb von siteUrl liegen, und URL-Präfix-Properties müssen mit / enden.

• Ungültige GA4-Metriken. Verwende die offizielle offline GA4-Dimensionen- und Metriknamen; alles andere wird von runReport abgelehnt.

Referenzen

• Claude Code MCP-Dokumentation

• Model Context Protocol

• Search Console API

• GA4 Data API

• Google Analytics Admin API

• Google-OAuth-Scopes

Lizenz

MIT. Siehe LICENSE.