youtube-analytics-mcp

Ein lokaler, schreibgeschützter MCP-Server, der Claude Zugriff auf die privaten Analysedaten deines YouTube-Kanals gibt – Aufrufe, Wiedergabezeit, Verweildauer, Abonnenten, Verkehrsquellen, Zielgruppendemografie, Einnahmen sowie Thumbnail-Impressionen/CTR. Nicht nur das, was jeder öffentliche API-Schlüssel bereits sehen kann.

Nichts in diesem Server kann etwas auf deinem Kanal bearbeiten, hochladen, veröffentlichen oder löschen. Siehe SECURITY.md für die vollständige Sicherheitsüberprüfung.

Requirements

• Node.js 22+

• Ein Google-Konto, das den YouTube-Kanal besitzt (oder verwaltet), für den du Daten möchtest

• macOS, Linux oder WSL (der npm run auth-Browserablauf verwendet den Befehl open)

Related MCP server: youtube-mcp-server

Setup checklist

Befolge diese in der Reihenfolge. Schritte 1–4 finden in der Google Cloud Console statt; Schritte 5–8 auf deinem Rechner.

1. Create a Google Cloud project

Gehe zu console.cloud.google.com und erstelle ein neues Projekt (oder wähle ein vorhandenes, mit dem du dich wohlfühlst).

2. Enable three APIs

Gehe in deinem Projekt zu APIs & Services → Bibliothek und aktiviere jede dieser APIs:

• YouTube Data API v3

• YouTube Analytics API

• YouTube Reporting API (nur für Thumbnail-Impressionen/CTR benötigt – siehe unten)

3. Configure the OAuth consent screen

Gehe zu APIs & Services → OAuth-Zustimmungsbildschirm.

• Benutzertyp: Extern (es sei denn, du hast ein Google Workspace-Konto, in diesem Fall funktioniert auch Intern)

• Fülle die erforderlichen Felder für App-Name / Support-E-Mail aus

• Füge die Analytics-Bereiche hinzu, wenn du dazu aufgefordert wirst (oder überspringe sie – die App fordert sie direkt an, dieser Bildschirm muss nur existieren)

• Veröffentliche die App als Produktion. Das ist der Schritt, den Leute überspringen und dann gegen eine Wand laufen: Apps im Modus „Testen“ erlauben nur die Anmeldung von Konten, die du explizit als Testbenutzer hinzugefügt hast, und ihre Aktualisierungstokens laufen nach 7 Tagen ab, was bedeutet, dass du Schritt 6 jede Woche wiederholen müsstest. Die Veröffentlichung als Produktion (ohne Einreichung zur Google-Verifizierungsprüfung) ist für ein persönliches Tool in Ordnung – Google zeigt beim Anmelden eine Warnung „Nicht verifizierte App“ an, und du klickst auf Erweitert → Zu [Name deiner App] wechseln (unsicher), um fortzufahren. Das ist erwartet und sicher für deine eigene App.

4. Create OAuth credentials

Gehe zu APIs & Services → Anmeldedaten → Anmeldedaten erstellen → OAuth-Client-ID.

• Anwendungstyp: Desktop-App

• Gib ihr einen beliebigen Namen

• Kopiere die generierte Client-ID und das Client-Geheimnis – du benötigst sie in Schritt 5

Hier muss keine Weiterleitungs-URI registriert werden; dieser Server bindet zur Authentifizierung einen temporären lokalen Port und Google akzeptiert für Desktop-Clients jede Loopback-Adresse.

5. Install and build

git clone <this-repo-url>
cd youtube-analytics-mcp
npm install
npm run build

6. Configure your credentials

cp .env.example .env

Bearbeite .env und füge die Client-ID / das Client-Geheimnis aus Schritt 4 ein:

GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret

.env ist gitignored – es wird niemals committet. Optionale Einstellungen:

• GOOGLE_API_KEY – für kein aktuelles Tool erforderlich, lasse es leer, es sei denn, du erweiterst den Server selbst.

• REVENUE_CURRENCY – standardmäßig USD. Setze es auf deine AdSense-Auszahlungswährung (z. B. BRL), wenn du die Einnahmen lieber in dieser Währung sehen möchtest; Google rechnet serverseitig um.

7. Authenticate

npm run auth

Dies öffnet deinen Browser für die Google-Anmeldung und speichert ein Aktualisierungstoken unter ~/.youtube-analytics-mcp/token.json (Berechtigungen nur für deinen Benutzer, niemals im Repository). Du musst dies nur einmal tun – der Server aktualisiert das Zugriffstoken danach automatisch.

Überprüfe, ob es funktioniert hat:

npm run auth:status

Du solltest Authenticated und den Namen deines Kanals sehen.

8. Point Claude Code at it

Füge es zu deiner MCP-Konfiguration hinzu, unter Verwendung des absoluten Pfads zu dist/index.js dieses Projekts:

{
  "mcpServers": {
    "youtube-analytics-channel": {
      "command": "node",
      "args": ["/absolute/path/to/youtube-analytics-mcp/dist/index.js"]
    }
  }
}

Starte Claude Code neu (oder lade die MCP-Server neu) und du solltest die unten verfügbaren Tools sehen.

Available tools

A note on impressions and CTR

YouTube stellt Thumbnail-Impressionen oder CTR nicht über die interaktive Analytics-API (reports.query) unter irgendeiner Dimensions-/Filterkombination bereit – dies wurde direkt gegen die API verifiziert, nicht aus Dokumentationen übernommen. Diese Daten existieren nur in YouTubes Bulk-„Reach-Bericht“, einer separaten asynchronen Job-API:

1. Der erste Aufruf von get_impressions_and_ctr registriert einen wiederkehrenden Berichtsauftrag bei Google.

2. Google benötigt 24–48 Stunden, um den ersten Bericht zu erstellen, und erstellt danach ungefähr täglich neue.

3. Jeder Aufruf von get_impressions_and_ctr (oder get_top_videos sortiert nach Impressionen/CTR) synchronisiert neu verfügbare Berichte in einen lokalen Cache unter ~/.youtube-analytics-mcp/reach-cache.json und antwortet dann aus diesem Cache.

Bis der erste Bericht eintrifft, geben diese Tools impressions: 0, impressionsCtr: null und einen note zurück, der erklärt, warum. Das ist bei der ersten Verwendung zu erwarten, kein Fehler.

Troubleshooting

• „Zugriff blockiert“ während npm run auth: Dein OAuth-Zustimmungsbildschirm befindet sich noch im Testmodus. Gehe zurück zu Schritt 3 und füge entweder dein Konto als Testbenutzer hinzu oder veröffentliche es als Produktion.

• NotAuthenticatedError beim Serverstart: Führe npm run auth aus.

• Einnahmen immer 0: Entweder ist der Kanal nicht monetarisiert, oder die Zahlen sind für diesen Zeitraum tatsächlich null. Das Tool erfindet niemals Einnahmen – überprüfe das Feld available von get_revenue_analytics, um einen echten Berechtigungs-/Zugriffsfehler von echten Nullen zu unterscheiden.

• get_impressions_and_ctr / nach Impressionen sortierte get_top_videos geben nichts zurück: Überprüfe dataCoverage in der Antwort. Wenn earliestDate null ist, hat der Bulk-Berichtsauftrag seinen ersten Bericht noch nicht erstellt (kann bis zu 48 Stunden nach dem allerersten Aufruf dauern).

Testing

npm test

Führt Unit-Tests (Node's eingebauter Test-Runner) aus, die Datums-/Zeitraumvalidierung, ISO-8601-Dauerparsing, CSV-Parsing, Analytics-Berichtszeilen-Zuordnung und Zeitraumvergleichsmathematik (einschließlich des Null-Division-Randfalls) abdecken. Dies sind nur reine Funktionstests – sie mocken keine Live-Google-API-Aufrufe oder OAuth-Token-Aktualisierung; diese Pfade wurden während der Entwicklung manuell gegen einen echten Kanal validiert.

Security

Siehe SECURITY.md für das vollständige Bedrohungsmodell und die OWASP-Top-10-Überprüfung. Kurzfassung: Alles ist schreibgeschützt, alle Geheimnisse bleiben auf deinem Rechner außerhalb des Repos, und jeder benutzerbereitgestellte Wert, der einen Google-API-Aufruf erreicht, wird zuerst validiert.

License

MIT – siehe LICENSE.