get_organic_traffic

Was dieses Tool tut

get_organic_traffic liefert eine 28-Tage-Momentaufnahme des organischen Traffics zu einem Audit, gezogen aus den verknüpften Google-Analytics-4- und Google-Search-Console-Properties des Nutzers.

• Liefert connected: false, wenn der Nutzer Google noch nicht verknüpft hat, die übrigen Felder sind dann leer.
• Wenn verknüpft: sessions_28d (organische Sessions gesamt), sessions_trend (Tagesreihe), top_landing_pages (URL + Sessions), top_queries (Query + Klicks + Impressions) und indexed_pages aus GSC.
• Serverseitig 24 Stunden pro Audit gecacht, also sind wiederholte Aufrufe günstig und idempotent.
• Immer an eine bestimmte audit_id gebunden; das Datenfenster ist relativ zum created_at dieses Audits.

Warum es wichtig ist

SEO-Audits ohne Traffic-Daten sagen Agenten, was zu fixen ist, aber nicht, was zuerst zu fixen ist. get_organic_traffic lässt einen Agenten fehlgeschlagene Seiten nach echtem organischen Wert ranken, damit die Empfehlungen auf URLs landen, die wirklich Umsatz bewegen.

Konkrete Workflows:

• Ein “Wo fange ich an?”-Agent ruft get_audit für Befunde und get_organic_traffic für Sessions auf und entwirft dann eine Fix-Liste, geordnet nach sessions_28d pro Landingpage.
• Ein Query-Gap-Agent liest top_queries (hohe Impressions, wenige Klicks) und schreibt Titel und Meta-Description der passenden Seite um, um die CTR zu heben.

So nutzt du es

Der Nutzer muss zuerst Google Analytics 4 und Search Console im MetricSpot-Dashboard verknüpfen. Wenn nicht verknüpft, gelingt das Tool trotzdem, es liefert connected: false, damit Agenten elegant degradieren und dem Nutzer sagen können, wie er Google verknüpfen soll.

Input-Schema

{
  "type": "object",
  "properties": {
    "audit_id": { "type": "string", "minLength": 1 }
  },
  "required": ["audit_id"]
}

Beispiel-Response

{
  "audit_id": "aud_01HZ8X9YP7K3T2N6Q5",
  "connected": true,
  "sessions_28d": 14328,
  "sessions_trend": [
    { "date": "2026-04-15", "sessions": 482 },
    { "date": "2026-04-16", "sessions": 511 },
    { "date": "2026-04-17", "sessions": 539 }
  ],
  "top_landing_pages": [
    { "url": "https://example.com/", "sessions": 5104 },
    { "url": "https://example.com/pricing", "sessions": 2871 },
    { "url": "https://example.com/blog/launch", "sessions": 1942 }
  ],
  "top_queries": [
    { "query": "example pricing", "clicks": 612, "impressions": 8412 },
    { "query": "example alternative", "clicks": 387, "impressions": 5101 }
  ],
  "indexed_pages": 184
}

Wenn Google nicht verknüpft ist:

{
  "audit_id": "aud_01HZ8X9YP7K3T2N6Q5",
  "connected": false,
  "sessions_28d": null,
  "indexed_pages": null
}

Claude Code

claude mcp add --transport http metricspot https://mcp.metricspot.com/mcp \
  --header "Authorization: Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Prompt:

Zieh für das MetricSpot-Audit aud_01HZ8X9YP7K3T2N6Q5 die Organic-Traffic-Momentaufnahme und sag mir, welche Top-10-Query die schlechteste CTR hat.

Cursor

.cursor/mcp.json:

{
  "mcpServers": {
    "metricspot": {
      "url": "https://mcp.metricspot.com/mcp",
      "headers": {
        "Authorization": "Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Prompt:

Kombiniere die Audit-Befunde mit get_organic_traffic und liste die fehlgeschlagenen Seiten auf, die die meisten Sessions bringen.

Python (Seiten nach Traffic ranken)

import httpx, json

HEADERS = {
    "content-type": "application/json",
    "accept": "application/json, text/event-stream",
    "authorization": "Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx",
}

r = httpx.post("https://mcp.metricspot.com/mcp", headers=HEADERS, json={
    "jsonrpc": "2.0", "id": 1, "method": "tools/call",
    "params": {
        "name": "get_organic_traffic",
        "arguments": {"audit_id": "aud_01HZ8X9YP7K3T2N6Q5"},
    },
}, timeout=30.0)

snap = json.loads(r.json()["result"]["content"][0]["text"])
if not snap["connected"]:
    print("Connect GA4 + GSC at app.metricspot.com/settings/integrations")
else:
    for q in snap.get("top_queries", [])[:5]:
        ctr = q["clicks"] / q["impressions"] if q["impressions"] else 0
        print(f"{q['query']}: CTR {ctr:.1%} ({q['clicks']} / {q['impressions']})")

Node / TypeScript (roher HTTP)

const res = await fetch("https://mcp.metricspot.com/mcp", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    accept: "application/json, text/event-stream",
    authorization: "Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx",
  },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: 1,
    method: "tools/call",
    params: {
      name: "get_organic_traffic",
      arguments: { audit_id: "aud_01HZ8X9YP7K3T2N6Q5" },
    },
  }),
});
const snap = JSON.parse((await res.json()).result.content[0].text);
if (snap.connected) {
  console.log(`${snap.sessions_28d} sessions in last 28d`);
}

Häufige Fehler

Code	Wann	Aktion
UNAUTHORIZED (401)	Fehlendes oder ungültiges Bearer-Token	Schlüssel ausstellen unter https://app.metricspot.com/settings/api-keys
AUDIT_NOT_FOUND (404)	audit_id gehört nicht zu diesem Konto	Rufe list_audits für gültige ids auf
FORBIDDEN (403)	Token fehlt der Google-Scope	Schlüssel mit Default-Scopes neu ausstellen, nachdem Google verknüpft wurde
UPSTREAM_FAILED (5xx)	GA4- oder GSC-API-Ausfall	Erneut versuchen; die Response wird nach Erfolg 24h gecacht

Häufig gestellte Fragen

Warum connected: false, obwohl ich Traffic in GA4 sehe?

Die Verknüpfung lebt auf MetricSpot-Seite: Der Nutzer muss app.metricspot.com/settings/integrations aufrufen und Google Analytics 4 und Search Console explizit verknüpfen. MetricSpot liest GA4 über die Analytics Data API und GSC über die Search Console API; beide brauchen OAuth-Grants, die der Nutzer einmal autorisiert.

Warum ein 28-Tage-Fenster?

Es passt dazu, wie GSC seine Top-Queries standardmässig reportet, und ist kurz genug, um aktuelle Änderungen (post-Deploy, post-Launch) zu spiegeln, aber lang genug, um wöchentliche Saisonalität zu glätten. Das Fenster ist in v1 nicht konfigurierbar.

Wie frisch sind die Daten?

GA4-Daten hinken üblicherweise 24-48 Stunden hinter Echtzeit her, gemäss Googles Verarbeitungsfenster. GSC-Daten haben 2-3 Tage Verzug. Die MCP-Response ist serverseitig 24 Stunden pro audit_id gecacht, also liefern wiederholte Aufrufe am selben Tag dieselbe Momentaufnahme.