YouTube Studio MCP

Ein MCP-Server zur Prüfung und Verbesserung der Auffindbarkeit eines YouTube-Kanals.

Er verbindet jeden MCP-fähigen KI-Agenten mit den Daten des eigenen Kanals: Katalog, Metriken der Analytics API, Retentionskurven, eingehende Suchbegriffe sowie Impressionen und Klickrate, die nur ein Studio-CSV-Export offenlegt. Anschließend bewertet er, was sich zu beheben lohnt – nach wiederherstellbaren Aufrufen statt nach Klickrate – siehe Wie Underperformer eingestuft werden.

Acht Tools: auth_status, list_videos, get_video, query_analytics, get_search_terms, get_retention_curve, import_studio_data und find_underperformers.

Alles ist schreibgeschützt und lokal: Der SQLite-Cache, Ihre OAuth-Tokens und Ihre Studio-Exporte verlassen niemals Ihren Rechner.

Voraussetzungen

• Node.js ≥ 22

• Ein Google-Konto, dem der YouTube-Kanal gehört

Related MCP server: MCP YouTube Intelligence

Einrichtung

1. Ein Google Cloud-Projekt erstellen und die APIs aktivieren

1. Gehen Sie zu https://console.cloud.google.com/ und erstellen Sie ein Projekt.

2. Aktivieren Sie YouTube Data API v3 und YouTube Analytics API. (Beide werden aktiv genutzt: Die Data API unterstützt die Katalogsynchronisierung sowie list_videos/ get_video, und die Analytics API unterstützt query_analytics, get_search_terms und get_retention_curve. Die Google Cloud Console erlaubt nur das Hinzufügen eines Einwilligungsbildschirm-Bereichs für eine API, die Sie aktiviert haben. Aktivieren Sie daher beide, bevor Sie mit dem nächsten Schritt fortfahren.)

2. Den OAuth-Zustimmungsbildschirm konfigurieren

1. Gehen Sie zu APIs & Dienste → OAuth-Zustimmungsbildschirm.

2. Wählen Sie Extern und füllen Sie die Pflichtfelder aus.

3. Fügen Sie diese Bereiche hinzu:

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

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

   • https://www.googleapis.com/auth/youtube.force-ssl

Wichtig – Veröffentlichen Sie die App als Produktivversion. Solange sich die App im Status Test befindet, läuft Googles Aktualisierungstoken nach 7 Tagen ab, sodass Sie sich jede Woche neu authentifizieren müssten. Klicken Sie auf App veröffentlichen. Die App bleibt unverifiziert, was in Ordnung ist: Sie sind der einzige Nutzer und greifen auf Ihre eigenen Daten zu. Sie sehen einmalig eine Warnung zur „unverifizierten App“ – wählen Sie Erweitert → Weiter zu (App-Name).

3. Den OAuth-Client erstellen

1. APIs & Dienste → Anmeldedaten → Anmeldedaten erstellen → OAuth-Client-ID.

2. Anwendungstyp: Desktop-App.

3. Laden Sie die JSON-Datei herunter.

4. Installieren und authentifizieren

npm install
npm run build

Speichern Sie die heruntergeladene OAuth-Client-JSON-Datei als credentials.json im Konfigurationsverzeichnis des Servers (erstellen Sie das Verzeichnis zuerst, falls es nicht existiert):

# Linux/macOS — adjust the source filename to match what Google actually
# named your download (it starts with "client_secret_")
mkdir -p ~/.config/youtube-studio-mcp
mv ~/Downloads/client_secret_*.json ~/.config/youtube-studio-mcp/credentials.json

# Windows (PowerShell) — same caveat about the source filename
New-Item -ItemType Directory -Force "$env:USERPROFILE\.config\youtube-studio-mcp" | Out-Null
Move-Item "$env:USERPROFILE\Downloads\client_secret_*.json" "$env:USERPROFILE\.config\youtube-studio-mcp\credentials.json"

Führen Sie dann aus:

node dist/index.js auth

Dadurch öffnet sich automatisch Ihr Browser. Autorisieren Sie dort, und die Tokens werden unter <Konfigurationsverzeichnis>/tokens.json gespeichert. Unter Linux/macOS wird die Datei mit nur für den Eigentümer lesbaren Berechtigungen geschrieben (chmod 600); Windows hat keine entsprechenden Dateiberechtigungsbits, daher ist dieser Schritt dort wirkungslos – verlassen Sie sich auf den normalen Dateischutz Ihres Benutzerkontos.

Falls sich kein Browser öffnet, schreibt der Befehl den Autorisierungslink auch in <Konfigurationsverzeichnis>/authorize-url.txt – öffnen Sie diese Datei und klicken Sie auf den Link. Kopieren Sie die URL nicht manuell aus Ihrem Terminal: Sie ist ~520 Zeichen lang, bricht über mehrere Zeilen um, und eine abgeschnittene Kopie schlägt bei Google mit dem irreführenden Fehler Required parameter is missing: response_type fehl (der fehlende Parameter befindet sich in dem abgeschnittenen Teil, nicht in der von uns erstellten Anfrage).

Setzen Sie YTMCP_HOME, um das Konfigurationsverzeichnis zu überschreiben (z. B. für einen zweiten Kanal oder ein Test-Setup). Es ersetzt den gesamten Pfad ~/.config/youtube-studio-mcp, sodass credentials.json, tokens.json und der SQLite-Cache alle mit verschoben werden.

5. Den Server bei Ihrem KI-Agenten registrieren

Der Server spricht standardmäßiges MCP über stdio, sodass jeder MCP-fähige Client ihn ausführen kann. Sie benötigen in jedem Fall eines: den absoluten Pfad zu dist/index.js in diesem Repository.

Die meisten Clients verwenden dieselbe JSON-Struktur. Ersetzen Sie Ihren eigenen Pfad:

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

Zwei Clients verwenden eine andere Struktur.

VS Code / GitHub Copilot — .vscode/mcp.json, mit dem Schlüssel servers, nicht mcpServers:

{
  "servers": {
    "youtube-studio": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/youtube-studio-mcp/dist/index.js"]
    }
  }
}

OpenAI Codex CLI — ~/.codex/config.toml, TOML statt JSON:

[mcp_servers.youtube-studio]
command = "node"
args = ["/absolute/path/to/youtube-studio-mcp/dist/index.js"]

Starten Sie den Agenten nach der Bearbeitung seiner Konfiguration neu. Bitten Sie ihn, auth_status auszuführen: Er sollte Ihren Kanal nennen und das verbleibende Kontingent melden. Wenn er Authenticated: NO meldet, führen Sie node dist/index.js auth erneut aus.

Wenn Ihr Client nicht aufgeführt ist, suchen Sie in seinen Einstellungen nach „MCP“ – der Befehl und die Argumente oben sind alles, was jeder von ihnen benötigt. Konfigurationspfade können sich zwischen Versionen ändern. Prüfen Sie daher die eigene Dokumentation Ihres Clients, falls ein hier genannter Pfad nicht existiert.

Ein Hinweis zum Agentenverhalten

Jedes Tool ist mit readOnlyHint: true annotiert, sodass Agenten, die diesen Hinweis anzeigen, nicht zur Bestätigung von Schreibvorgängen auffordern. Nichts in diesem Server verändert Ihren Kanal – das Zurückschreiben von Metadaten ist eine spätere Stufe.

list_videos bedient sich aus dem lokalen Cache, sofern keine Synchronisierung angefordert wird, und find_underperformers und import_studio_data greifen überhaupt nicht auf das Netzwerk zu. Nur explizite Synchronisierungen und Analytics- Abfragen verbrauchen Kontingent, was wichtig ist, da Agenten explorativ vorgehen: Ein Agent, der list_videos zwanzigmal aufruft, kostet nichts, während zwanzig Katalogsynchronisierungen das Tagesbudget erschöpfen würden. auth_status meldet, was übrig ist.

Tools

list_videos bedient sich vollständig aus dem lokalen SQLite-Cache, sofern Sie nicht sync: true übergeben – einfache Lesevorgänge (Filtern nach Shorts/Langform, Aufrufzahl, Veröffentlichungsdatum, Titel oder Sortierung) kosten kein Kontingent. Wenn noch nichts synchronisiert wurde, werden Sie aufgefordert, es erneut mit sync: true aufzurufen, statt eine leere Liste zurückzugeben.

get_search_terms und get_retention_curve speichern ihre Ergebnisse pro Datumsfenster zwischen (siehe Kontingent unten); query_analytics speichert nicht zwischen und führt immer einen Live-Aufruf aus. get_search_terms gibt höchstens 25 Zeilen zurück – Google begrenzt den zugrunde liegenden Bericht dort, sodass ein größeres Datumsfenster ändert, welche Begriffe in den Top 25 rangieren, nicht wie viele Zeilen zurückkommen.

Kontingent

YouTube gewährt 10.000 Einheiten/Tag plus separate 100 search.list-Aufrufe/Tag. Der Server verfolgt beides und hält eine Reserve zurück (500 Einheiten, 10 Suchaufrufe), sodass ein Massenvorgang interaktive Tools nicht unbrauchbar machen kann. Das Kontingent wird um Mitternacht Pazifikzeit zurückgesetzt, was auth_status meldet.

Eine vollständige Katalogsynchronisierung (list_videos mit sync: true) führt einen channels.list- Aufruf aus, blättert dann durch die Upload-Playlist (playlistItems.list, 50 Videos pro Seite) und ruft Videodetails in Stapeln ab (videos.list, 50 IDs pro Aufruf), wobei jeder Aufruf 1 Einheit kostet. Das ergibt 1 + ceil(videos/50) + ceil(videos/50) Einheiten – etwa 5 Einheiten für einen Kanal mit 100 Videos.

Die YouTube-Analytics-API hat ihr eigenes Pro-Projekt-Kontingent in der Cloud Console, getrennt von den 10.000 Einheiten der Data API. Analytics-Aufrufe werden im lokalen Protokoll zu null Einheiten erfasst, sodass auth_status nicht anzeigt, dass sie Ihr Data-API-Budget belasten.

Suchbegriff-Ergebnisse und Retentionskurven werden pro Datumsfenster zwischengespeichert, da die zugrunde liegenden Berichte ein eingestuftes Top-N über einen Bereich statt tagesweiser Zeilen zurückgeben. Ein wiederholter Aufruf mit denselben Daten wird aus dem Cache bedient; übergeben Sie refresh: true, um erneut abzufragen.

Impressionen und CTR importieren

impressions und impressionClickThroughRate existieren nicht in der YouTube Analytics API – sie sind nur in Studio verfügbar. So erhalten Sie sie:

1. YouTube Studio → Analytics → Erweiterter Modus (oben rechts)

2. Stellen Sie sicher, dass die Spalten Impressionen und Klickrate der Impressionen sichtbar sind – der Export enthält nur die aktuell auf dem Bildschirm sichtbaren Spalten

3. Exportieren → Kommagetrennte Werte (.csv) – Sie erhalten eine ZIP-Datei mit drei Dateien

4. Entpacken Sie sie und führen Sie dann import_studio_data mit dem Ordnerpfad aus

import_studio_data liest nur eine Datei von der Festplatte – es ruft niemals die YouTube Data API oder die Analytics API auf, benötigt also keine Authentifizierung und kostet kein API-Kontingent.

Das Datumsfenster wird aus dem Ordnernamen gelesen (Studio benennt ihn z. B. Contenido 2010-01-26_2026-08-09 Channel). Um es zu überschreiben, übergeben Sie beide rangeStart und rangeEnd (YYYY-MM-DD) – die Angabe nur eines Werts wird mit einem Validierungsfehler abgelehnt, statt stillschweigend auf das Fenster aus dem Ordnernamen zurückzufallen, da dies Daten ohne Warnung unter den falschen Daten landen lassen könnte. Beide Daten müssen echte Kalenderdaten sein (2026-13-45 wird abgelehnt, nicht umgebrochen), und rangeStart darf nicht nach rangeEnd liegen.

Impressionen und CTR sind ein Gesamtbereichs-Aggregat. Von den drei Dateien im Export enthält nur die Pro-Video-Tabelle (Datos de la tabla.csv / Table data.csv) Impressionen und CTR, und sie meldet eine Zeile pro Video, summiert über den gesamten Datumsbereich — es gibt nirgendwo im Export eine tägliche CTR. Die Tagesdatei (Datos del gráfico.csv / Chart data.csv) und die Kanal-Gesamtwerte-Datei (Totales.csv / Totals.csv) enthalten nur Aufrufe. Ein Vergleich über die Zeit bedeutet also, mehrere Exporte mit unterschiedlichen Bereichen zu importieren, nicht einen einzelnen zu zerschneiden.

import_studio_data akzeptiert entweder den Exportordner oder einen bestimmten CSV-Pfad. Zeigst du es auf den Ordner, findet es die Tabellendatei automatisch. Zeigst du es direkt auf eine der anderen beiden Dateien, wird der Import sofort abgelehnt: Der Header einer CSV sagt dir eindeutig, um welchen der drei Berichte es sich handelt (reportType ist table, chart oder totals — siehe src/studio/csvSchemas.ts), und nur table enthält etwas, das dieser Importer speichern kann. Die Diagrammdatei hat zwar eine Video-ID, sodass ein naiver Import stillschweigend erfolgreich wäre, dabei aber Impressionen/CTR mit NULL und Aufrufe mit der Zahl des letzten Tages statt der Bereichssumme überschreiben würde; die Gesamtwerte-Datei hat überhaupt keine Video-ID. Beide werden abgelehnt, bevor etwas geschrieben wird, mit einer Meldung, die Datos de la tabla.csv / Table data.csv als die Datei nennt, auf die stattdessen gezeigt werden soll.

Zeilen für Videos, die nicht mehr öffentlich sind, werden gespeichert und als unzugeordnet gemeldet; das ist erwartet, kein Fehler.

Shorts

Ein Video zählt nur dann als Short, wenn es 180 Sekunden oder kürzer ist und am oder nach dem 14.09.2020 veröffentlicht wurde, dem Tag, an dem Shorts gestartet wurden.

Die Dauer allein reicht nicht aus. Bei einem Katalog von natürlich kurzen Long-Form-Videos — Musikvideos, Edits, Trailer — führt eine reine Dauerregel zu massiven Fehlklassifizierungen. Eine Live-Überprüfung an einem ruhenden Kanal von vor 2020 markierte rund 70 % seines Katalogs als Shorts, jeder einzelne davon ein Fehlalarm: Der neueste Upload des Kanals ging dem Shorts-Start um Monate voraus, also konnte keiner davon echt sein.

find_underperformers liest dieses Flag über seinen cohort-Parameter. Die Übergabe von cohort: 'short' oder cohort: 'long' beschränkt die Baseline auf diese Hälfte des Katalogs, sodass Shorts und Long-Form nur mit ihresgleichen verglichen werden. Der Standardwert cohort: 'all' führt diese Segmentierung nicht durch — er fasst beide zu einer einzigen gemischten Baseline zusammen. Bei einem Katalog, der bereits eine Kohorte ist (der reale Fall dieses Nutzers, vollständig Long-Form), ist das Zusammenfassen ein No-op, aber bei einem gemischten Katalog vermischt der Standardwert zwei Populationen mit unterschiedlichen typischen CTRs; übergib cohort explizit, um sie zu segmentieren. Ein falsches Flag bei einem Video würde selbstbewussten Unsinn statt eines offensichtlichen Fehlers erzeugen, weshalb die Veröffentlichungsdatum-Prüfung wichtig ist.

Wie Underperformer eingestuft werden

find_underperformers sortiert nach rückgewinnbaren Aufrufen, nicht nach Klickrate:

recoverable views = impressions x (baseline CTR - video CTR) / 100

Das ist eine Schätzung der Aufrufe, die ein Video bei der eigenen Baseline des Kanals gewonnen hätte — die Größe, auf die es sich zu handeln lohnt. Eine reine CTR-Sortierung ist in dreierlei Hinsicht irreführend:

• Impressionen konzentrieren sich. Der Großteil der Impressionen eines Kanals liegt in einem kleinen Bruchteil seiner Videos, sodass „schlechteste CTR“ und „größte Chance“ nahezu disjunkte Mengen sind. Das Video mit dem hässlichsten Verhältnis ist oft eines, das fast niemandem gezeigt wurde.

• Null Impressionen erzeugen eine 0 % CTR durch Division, nicht durch Leistung. Eine aufsteigende Sortierung setzt jedes nie gezeigte Video an die Spitze der Liste der zu behebenden Dinge, was genau verkehrt herum ist.

• Die höchste CTR auf einem Kanal hat meist einen winzigen Nenner — eine Handvoll Impressionen, die zufällig konvertiert sind. Es ist Rauschen, das als Triumph präsentiert wird.

Daraus ergeben sich zwei Regeln. Videos unterhalb einer Impressions-Untergrenze werden als unzureichende Daten gemeldet und nie als schlechte Performer eingestuft. Und die Baseline ist impressionsgewichtet, weil ein ungewichteter Mittelwert von Videos mit wenig Traffic dominiert wird und fast nichts von dem Traffic beschreibt, den der Kanal tatsächlich bekommt.

Jede Gelegenheit ist typisiert. weak_metadata bedeutet, dass der Metadaten-Score niedrig genug ist, dass es das Erste ist, was zu beheben ist; low_ctr bedeutet, dass die Metadaten bereits solide sind und das Thumbnail oder die Titelgestaltung der Hebel ist.

Entwicklung

npm test          # unit tests, no network
npm run typecheck
npm run build

npm run typecheck führt zwei Projekte aus: tsconfig.json (src/**, der Build) und tsconfig.test.json (src/** + test/** + vitest.config.ts, nur noEmit). Führe nur das Testprojekt mit npm run typecheck:test aus. Vitest selbst entfernt Typen nur über esbuild und führt keine Typprüfung durch, also ist npm run typecheck das, was einen Typfehler in einer Testdatei tatsächlich erkennt.