Inoffizieller Google Trends MCP-Server

⚠️ Inoffizielles Projekt. Nicht mit Google verbunden, von Google unterstützt oder befürwortet. Google Trends hat keine allgemein verfügbare öffentliche API, daher liest dieser Server dieselben öffentlich zugänglichen Endpunkte, die auch die Website trends.google.com verwendet (über trendspy) – was bedeutet, dass Google ihn jederzeit ohne Vorankündigung drosseln oder unterbrechen kann. Nutzung auf eigene Gefahr; lesen Sie Einschränkungen, bevor Sie sich darauf verlassen.

Ein Model Context Protocol-Server, der KI-Assistenten – Claude, ChatGPT, Cursor oder jeden MCP-Client – Zugriff auf Google-Trends-Daten bietet: Suchinteresse im Zeitverlauf, regionale Aufschlüsselungen, Trend-Suchen und Keyword-Ideen.

Läuft als Remote-MCP-Server (streamable HTTP), entwickelt für Google Cloud Run – Sie hosten ihn in Ihrem eigenen Google-Cloud-Projekt und verbinden ihn mit Ihrem KI-Assistenten Ihrer Wahl. Funktioniert auch lokal über stdio.

Verbinden Sie ihn mit Ihrem KI-Assistenten

Nach der Bereitstellung (siehe Setup) haben Sie eine Endpunkt-URL wie https://<your-service>.run.app/<secret>/mcp. Alle Tools sind schreibgeschützt.

Claude (Web/Desktop): Einstellungen → Connectors → Benutzerdefinierten Connector hinzufügen → URL einfügen. Funktioniert mit Pro-, Max-, Team- und Enterprise-Plänen.

ChatGPT (Web): Aktivieren Sie den Entwicklermodus (Einstellungen → Apps → Erweiterte Einstellungen), dann Einstellungen → Apps → Erstellen, fügen Sie die URL als MCP-Server-Endpunkt ein, wählen Sie Keine Authentifizierung (die Zugriffskontrolle ist das Geheimnis in der URL), klicken Sie auf Tools scannen → Erstellen. Benutzerdefinierte MCP-Connectors erfordern einen kostenpflichtigen Plan; bei Pro sind Connectors auf schreibgeschützte Tools beschränkt – was dieser Server ausschließlich hat, also funktioniert es.

Claude Code / Cursor / andere MCP-Clients: Jeder Client, der Remote-MCP über streamable HTTP unterstützt, funktioniert, z. B. claude mcp add --transport http google-trends <URL>. Für lokale/stdio-Setups siehe docs/setup-advanced.md.

Related MCP server: youtube-trends-mcp

So funktioniert es

AI assistant (Claude · ChatGPT · Cursor · any MCP client)
   │  MCP over streamable HTTP, at https://<cloud-run-url>/<secret>/mcp
   ▼
server.py — FastMCP tool layer (stateless, JSON responses)
   │  TrendsBackend interface (swappable, see backends/)
   ▼
backends/trendspy_backend.py
   │  1. TTL cache — identical queries answered from memory
   │     (12 h series · 15 min trending · 24 h autocomplete)
   │  2. Circuit breaker — after a 429: cooldown, fail fast with
   │     a clear "retry in Ns" message (no hammering Google)
   │  3. One upstream call at a time, ≥3 s apart
   ▼
Google's public endpoints
   ├─ trends.google.com (unofficial, same as the website uses)
   └─ suggestqueries.google.com (Autocomplete, for keyword_ideas)

Die Zugriffskontrolle ist ein zufälliges geheimes Pfadsegment in der URL (bei der Bereitstellung generiert, in einer gitignorierten .mcp_secret-Datei gespeichert) – verwendet, weil die meisten Chat-Clients mit benutzerdefinierten Connector-Oberflächen (Claude, ChatGPT) keine Auth-Header senden können. Der Cloud-Run-Dienst ist absichtlich auf eine Instanz begrenzt: Eine Instanz = eine IP und ein gemeinsamer Cache, was die Ratenbegrenzung von Google vorhersehbar hält. Er skaliert im Leerlauf auf null, sodass das Hosting bei persönlicher Nutzung ~kostenlos ist.

Tools

Daten-Backends

Die Datenschicht ist austauschbar (siehe backends/):

• trendspy (Standard) – verwendet trendspy, das mit denselben inoffiziellen Endpunkten wie die Trends-Website kommuniziert. Kostenlos, kein API-Schlüssel, aber pro IP ratenbegrenzt und könnte brechen, wenn Google seine Endpunkte ändert.

• official (Stub) – für Googles offizielle Trends-API (Alpha), die anwendungsbasiert freigeschaltet wird. Verdrahten Sie backends/official_backend.py, sobald Google Ihrem Projekt Zugriff gewährt, und setzen Sie dann TRENDS_BACKEND=official. Der MCP-Toolvertrag bleibt identisch.

⚠️ Werte von Google Trends sind relatives Suchinteresse (0–100 innerhalb jeder Abfrage), keine absoluten Suchvolumina.

Setup

Zwei Anleitungen, wählen Sie Ihr Tempo:

• Anfängeranleitung – noch nie ein Terminal oder Google Cloud benutzt? Vollständige Schritt-für-Schritt-Anleitung von null, ~15 Minuten.

• Fortgeschrittenenanleitung – erfahren? Klonen → ./deploy.sh → verbinden; plus lokaler stdio-Modus, Konfigurationsreferenz und Architekturhinweise.

In Cloud Run bereitstellen (Kurzversion)

gcloud auth login
./deploy.sh YOUR_PROJECT_ID europe-west1

Das Skript aktiviert die erforderlichen APIs, baut den Container mit Cloud Build, stellt mit Scale-to-Zero bereit (≈ kostenlos bei geringer Nutzung) und gibt Ihren MCP-Endpunkt aus:

https://google-trends-mcp-xxxxx.a.run.app/<secret>/mcp

Das zufällige <secret>-Pfadsegment ist das Zugriffstoken – der Dienst ist technisch öffentlich, aber ohne die vollständige URL nicht erreichbar. Halten Sie es geheim und führen Sie die Bereitstellung mit einem neuen Geheimnis erneut aus, um es zu rotieren.

Verbinden Sie Ihren KI-Assistenten

Siehe Verbinden Sie ihn mit Ihrem KI-Assistenten oben für Claude und ChatGPT. Claude Code:

claude mcp add --transport http google-trends https://google-trends-mcp-xxxxx.a.run.app/<secret>/mcp

Lokal ausführen

pip install -r requirements.txt
python server.py
# MCP endpoint at http://localhost:8080/mcp

Konfiguration

Einschränkungen & bekannte Probleme

Lesen Sie dies, bevor Sie sich auf den Server verlassen – diese Punkte sind strukturell, keine Fehler:

1. Inoffizielle Datenquelle. Es gibt keine öffentliche Google-Trends-API (Googles offizielle API ist Alpha und nur auf Einladung). Dieser Server verwendet die eigenen Endpunkte der Website, die Google jederzeit ändern oder blockieren kann. Wenn Google etwas ändert, funktioniert der Server nicht mehr, bis trendspy aufholt – genau das ist 2025 mit der älteren pytrends-Bibliothek passiert.

2. related_queries und related_topics sind praktisch tot. Google erzwingt ein nahezu Null-Kontingent für diese beiden „Widget“-Endpunkte für automatisierte (Nicht-Browser-)Clients. Das Limit gilt pro Client-Fingerabdruck, nicht pro IP – Proxys, VPNs und lokale Ausführung helfen nicht. Erwarten Sie, dass diese Tools meistens beim ersten Aufruf fehlschlagen; die Fehlermeldung sagt dies und verweist auf keyword_ideas (Google Autocomplete), die zuverlässige Alternative für Keyword-Recherche.

3. Ratenbegrenzung für alles andere. Die funktionierenden Endpunkte (Interesse im Zeitverlauf, nach Region, Trends) sind ebenfalls pro IP ratenbegrenzt. Bursts von Anfragen führen zu HTTP-429ern. Die Maßnahmen des Servers (unten) machen dies bei normaler Nutzung selten, aber starke automatisierte Abfragen stoßen an die Grenze.

4. Relative Werte, keine Volumina. Alle Trends-Zahlen sind 0–100 innerhalb jeder Abfrage (100 = der Höhepunkt für dieses Begriffsset/Zeitraum/Geo). Sie sind keine absoluten Suchvolumina und nicht über separate Abfragen hinweg vergleichbar.

5. Frische-Kompromiss. Ergebnisse werden zwischengespeichert (12 h für Seriendaten, 15 min für Trends, 24 h für Autocomplete), um unter den Ratenlimits zu bleiben – Sie können absichtlich leicht veraltete Daten sehen.

6. Einzelne Instanz. Bereitgestellt mit --max-instances 1, also für persönliche/Kleinteam-Nutzung, nicht für hochparallelen Produktionsverkehr.

Ratenlimits & wie der Server darum herum entworfen ist

Google begrenzt die inoffiziellen Trends-Endpunkte. Der Server mildert dies in Schichten:

• TTL-Cache – identische Abfragen werden aus dem Speicher bedient (~12h für Seriendaten, 15 min für Trends, 24h für Autocomplete) und treffen Google nie zweimal.

• Abstand + Serialisierung – ein Upstream-Aufruf gleichzeitig, mit einer TRENDS_REQUEST_DELAY-Pause (Standard 3s) zwischen Aufrufen.

• Retry + Circuit Breaker – ein sanfter Retry bei 429, dann eine Abkühlphase (120s), während der neue Abfragen schnell mit einer klaren „Retry in Ns“-Meldung fehlschlagen, statt Google zu hämmern. Zwischengespeicherte Abfragen funktionieren während der Abkühlung weiter.

• Nutzungsregeln an den KI-Client weitergegeben über MCP-Anweisungen: Bündeln Sie bis zu 5 Begriffe pro interest_over_time-Aufruf, planen Sie Aufrufe statt sie zu sprühen, wiederholen Sie einen Ratenlimit-Fehler niemals automatisch.

• related_queries / related_topics Realität: Google hat diese beiden Widget-Endpunkte für automatisierte (Nicht-Browser-)Clients auf nahezu Null-Kontingent gesenkt – dies ist pro Fingerabdruck, daher helfen Proxys und IP-Änderungen nicht. Erwarten Sie, dass sie fehlschlagen; der Fehler erklärt dies. Verwenden Sie stattdessen keyword_ideas (Google Autocomplete) für Keyword-Recherche – es ist schnell, zuverlässig und nicht an das Trends-Kontingent gebunden.

--max-instances 1 im Bereitstellungsskript ist beabsichtigt: Eine Instanz = eine IP und ein gemeinsamer Cache = vorhersehbare Ratenbegrenzung.

Tipps für Benutzer

Bitten Sie um Vergleiche in einem Zug („vergleiche A vs. B vs. C in PT über 12 Monate“ → ein API-Aufruf) statt einen Begriff nach dem anderen. Wiederholungen kürzlicher Fragen sind kostenlos (Cache). Wenn Sie eine Abkühlmeldung erhalten, warten Sie einfach die angegebenen Sekunden – spammen Sie keine Retries. Fragen Sie für „was suchen Leute rund um X“ nach Keyword-Ideen statt verwandten Abfragen.

Sicherheitshinweise

Alles in diesem Repository ist generisch – keine Anmeldeinformationen, Schlüssel, Projekt-IDs oder persönliche Daten. Zwei Dinge bleiben lokal auf Ihrem Rechner und dürfen niemals committet werden:

• .mcp_secret – die zufällige Zeichenfolge in Ihrer Endpunkt-URL. Sie ist das Einzige, das Fremde daran hindert, Ihren bereitgestellten Server aufzurufen, also behandeln Sie sie wie ein Passwort. deploy.sh generiert sie beim ersten Lauf und bewahrt sie hier auf, sodass erneute Bereitstellungen dieselbe URL verwenden. Sie ist gitignoriert. (Sie hat nichts mit GitHub zu tun – es ist kein GitHub-Token und hat keinen Zugriff auf Ihr Konto.)

• Ihre Google-Cloud-Projekt-ID – wird als Befehlszeilenargument an deploy.sh übergeben, nie in eine Datei im Repository geschrieben.

Um das Geheimnis zu rotieren (z. B. wenn die URL durchgesickert ist): Löschen Sie .mcp_secret, führen Sie ./deploy.sh <PROJECT_ID> erneut aus und aktualisieren Sie die URL in den Connector-Einstellungen Ihres KI-Assistenten. Die alte URL funktioniert sofort nicht mehr.

Stellen Sie vor Ihrem ersten Push sicher, dass nichts Sensibles bereitgestellt ist:

git status --short          # .mcp_secret and .env must NOT appear
git check-ignore -v .mcp_secret

Haftungsausschluss

Inoffizielles Community-Projekt; nicht mit Google verbunden, von Google unterstützt oder befürwortet. „Google Trends“ und „Google“ sind Marken von Google LLC, die hier nur zur Beschreibung verwendet werden, womit die Software verbunden ist. Trends-Daten werden über öffentlich zugängliche Endpunkte abgerufen; Sie sind dafür verantwortlich, sie in Übereinstimmung mit den Nutzungsbedingungen von Google und auf eigene Gefahr zu verwenden. Keinerlei Garantie – Endpunkte können jederzeit aufhören zu funktionieren.

Lizenz

MIT