YouTube MCP Server

Ein Open-Source-Server für das Model Context Protocol (MCP), der YouTube über MCP-Clients wie Claude Desktop, Claude Code und Codex nutzbar macht.

Der primäre Arbeitsablauf ist:

1. Gib einem MCP-Client eine Liste von Songs.

2. Prüfe die nach Relevanz sortierten YouTube-Treffer, bevor irgendetwas geändert wird.

3. Erstelle eine private Playlist aus den ausgewählten Videos.

Der Server stellt außerdem quota-bewusste Tools zum Durchsuchen von YouTube und zum Lesen von Videos, Kanälen, Playlists und Kommentaren bereit.

[!IMPORTANT] Das TypeScript-Paket, der stdio-Server, öffentliche und authentifizierte Lesevorgänge, PKCE-OAuth, die Musikvorbereitung, die bestätigte Erstellung neuer Playlists und vollständige, per Vorschau abgesicherte Playlist-Mutationen sind implementiert und getestet. Das direkte Hinzufügen eines vorbereiteten Musikentwurfs zu einer bestehenden Playlist bleibt geplant: Derzeit können Songs nur beim Erstellen der Playlist eingefügt werden.

Designziele

• Sichere Playlist-Schreibvorgänge mit Preview-vor-Commit-Semantik.

• Ausschließlich offizielle Endpoints der YouTube Data API v3.

• Eigener Google-OAuth-Client (Bring-your-own); das Projekt enthält niemals gemeinsame Google-Anmeldedaten.

• Geheimnisse werden wann immer möglich im Schlüsselbund des Betriebssystems gespeichert.

• Vorhersehbare Quota-Nutzung, Paginierung, Caching, Wiederholungen und normalisierte Fehler.

• Lokaler stdio-Transport für eine einfache Installation und eine kleine Angriffsfläche.

• Strukturierte, begrenzte Tool-Ausgaben, die YouTube-Inhalte als nicht vertrauenswürdige Daten behandeln.

• Plattformübergreifende TypeScript-Unterstützung auf Node.js 20.17 oder neuer.

Geplanter Umfang für v1

Lese-Tools

• Videos, Kanäle und Playlists durchsuchen.

• Video-, Kanal-, Playlist- und Kommentardaten lesen.

• Den Kanal, die Uploads und die Playlists des authentifizierten Benutzers lesen.

• Provider-Seitentokens für explizite, zustandslose Paginierung zurückgeben.

Musik-Playlist-Workflow

• Bis zu 50 strukturierte Tracks pro Vorbereitungsanfrage akzeptieren.

• Wahrscheinliche YouTube-Musikvideo-Treffer suchen und ordnen.

• Mehrdeutigkeiten und Alternativen anzeigen, anstatt schwache Treffer stillschweigend auszuwählen.

• Explizit ausgewählte Treffer in eine neue Playlist übernehmen. Ein bestehendes Playlist-Ziel ist geplant.

• Neue Playlists standardmäßig auf private setzen.

Playlist-Verwaltung

• Playlists erstellen und Videos hinzufügen.

• Playlist-Metadaten oder Datenschutzeinstellungen aktualisieren.

• Playlist-Elemente neu anordnen oder entfernen.

• Playlists löschen, nachdem ein kurzlebiges Einmal-Bestätigungs-Handle ausgestellt wurde.

Playlist-Updates, das Entfernen/Neuanordnen von Elementen und das Löschen verwenden zwei Tools: youtube_prepare_playlist_mutation gibt das exakte Diff und ein 10-Minuten-Handle zurück, ohne zu schreiben; youtube_apply_playlist_mutation prüft Eigentümerschaft und Playlist-Snapshot erneut, bevor es dieses Handle genau einmal verbraucht.

Schreibvorgänge außerhalb der Playlist-Verwaltung – Uploads, Kommentare, Bewertungen, Abonnements und Kanaländerungen – sind bewusst ausgeschlossen.

Einrichtung

Das npm-Paket wurde noch nicht veröffentlicht, daher wird der Server aus einem Klon erstellt und ausgeführt. Arbeite die Schritte der Reihe nach durch.

Schritt 1 – Node.js und npm prüfen

node -v
npm -v

Wenn node -v v20.17 oder neuer ausgibt und npm -v eine Version ausgibt, springe zu Schritt 3. Wenn einer der Befehle „command not found“ meldet, fahre mit Schritt 2 fort.

Schritt 2 – Node.js und npm installieren (nur wenn Schritt 1 fehlgeschlagen ist)

npm wird mit Node.js ausgeliefert; die Installation von Node installiert beides. Wähle eine Zeile für deine Plattform und führe dann Schritt 1 erneut aus, um zu bestätigen.

Wenn du Node nicht systemweit installieren möchtest oder mehrere Node-Versionen parallel benötigst, verwende einen Versionsmanager:

# macOS and Linux
curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
nvm install 22
nvm use 22

Unter Windows ist das Pendant nvm-windows: nvm install 22 und dann nvm use 22.

Schließe das Terminal nach der Installation und öffne es erneut; führe dann node -v und npm -v erneut aus.

Schritt 3 – Abhängigkeiten installieren und bauen

git clone <repository-url>
cd "Youtube MCP"
npm ci
npm run build

npm ci installiert die exakten Versionen aus package-lock.json; verwende npm install nur, wenn du Abhängigkeiten ändern willst. Der Build schreibt die ausführbare Datei nach dist/cli/index.js, die jeder untenstehende Befehl aufruft.

Überprüfe den Build und das lokale Datenverzeichnis:

node dist/cli/index.js doctor

Schritt 4 – Google-Anmeldedaten erstellen

Alles unten stammt aus deinem eigenen Google-Cloud-Projekt. Dieses Projekt enthält niemals gemeinsame Google-Anmeldedaten.

1. Erstelle oder wähle ein Projekt in der Google Cloud console.

2. Aktiviere YouTube Data API v3 für dieses Projekt.

3. Erstelle einen API-Schlüssel (Credentials → Create credentials → API key). Dieser deckt öffentliche Lesevorgänge ab.

4. Konfiguriere den OAuth-Zustimmungsbildschirm. Solange sich das Projekt im Testing-Status befindet, füge unter Test users dein eigenes Google-Konto hinzu, sonst wird login verweigert.

5. Erstelle einen OAuth-Client vom Typ Desktop-App und kopiere sowohl Client-ID als auch Client-Secret.

Google verlangt client_secret auch bei installierten Anwendungen im Authorization-Code-Austausch; PKCE ergänzt das Secret hier also, ersetzt es aber nicht.

Schritt 5 – Die benötigten Anmeldedaten des Servers

Insgesamt gibt es vier Credentials. Die ersten drei gibst du an; das vierte erhältst du über login.

Optionale Umgebungsvariablen: YOUTUBE_MCP_PROFILE (Standard: default), YOUTUBE_MCP_DATA_DIR und YOUTUBE_MCP_LOG_LEVEL (error, warn, info, debug). Siehe .env.example.

Füge keine dieser Angaben jemals in eine Chatnachricht, eine gemeinsame MCP-Konfigurationsdatei oder einen Befehl ein, der committet wird. Bevorzuge die interaktiven Eingabeaufforderungen oder das Umgebungs-/Secret-Injection-Feld deines Clients.

Schritt 6 – setup ausführen, dann anmelden

Führe sie der Reihe nach aus. setup überschreibt die gespeicherten Scopes und die Kanalidentität des Profils. Wenn du es nach login ausführst, wird dieser Zustand verworfen und eine erneute Anmeldung ist erforderlich.

macOS und Linux:

YOUTUBE_OAUTH_CLIENT_ID="YOUR_DESKTOP_CLIENT_ID" \
  YOUTUBE_OAUTH_CLIENT_SECRET="YOUR_DESKTOP_CLIENT_SECRET" \
  node dist/cli/index.js setup
node dist/cli/index.js login
node dist/cli/index.js status

Windows PowerShell:

$env:YOUTUBE_OAUTH_CLIENT_ID  = "YOUR_DESKTOP_CLIENT_ID"
$env:YOUTUBE_OAUTH_CLIENT_SECRET = "YOUR_DESKTOP_CLIENT_SECRET"
node dist\cli\index.js setup
node dist\cli\index.js login
node dist\cli\index.js status
Remove-Item Env:\YOUTUBE_OAUTH_CLIENT_SECRET

Um das Secret vollständig aus der Shell-Historie oder der Prozesstabelle herauszuhalten, lass beide Variablen weg und lass setup danach fragen:

node dist/cli/index.js setup

setup fragt nach jedem fehlenden Wert, wenn das Terminal interaktiv ist.

login öffnet Googles Autorisierungsseite und kehrt über einen zufälligen Loopback-Port auf 127.0.0.1 zurück, wobei PKCE S256 und ein zufälliger State-Wert verwendet werden. Wenn für das Profil kein Client-Secret gespeichert ist, schlägt es sofort fehl, bevor ein Browser geöffnet wird.

Um das gespeicherte Credential zu widerrufen und zu entfernen:

node dist/cli/index.js logout

Schritt 7 – Server starten

YOUTUBE_API_KEY="your-api-key" node dist/cli/index.js serve

Der Server spricht MCP über stdio und wird daher normalerweise von einem Client gestartet statt von Hand. Verfügbare Befehle sind serve, doctor, status, setup, login und logout.

Speicherort lokaler Daten

Profile, das Quota-Kontobuch, Entwürfe und Operationsjournale liegen in einem Verzeichnis mit 0700-Berechtigungen:

Überschreibe den Pfad mit YOUTUBE_MCP_DATA_DIR. Um den gesamten lokalen Zustand zu entfernen, führe logout aus und lösche dann dieses Verzeichnis. Schlüsselbund-Einträge werden durch logout entfernt.

Einen Client mit dem lokalen Build verbinden

Bis das Paket veröffentlicht ist, richte Clients auf den absoluten Pfad deines gebauten dist/cli/index.js aus.

Claude Code

claude mcp add youtube --scope user \
  --env YOUTUBE_MCP_PROFILE=default \
  --env YOUTUBE_API_KEY=your-api-key -- \
  node /absolute/path/to/Youtube\ MCP/dist/cli/index.js serve

Claude Desktop

{
  "mcpServers": {
    "youtube": {
      "command": "node",
      "args": ["/absolute/path/to/Youtube MCP/dist/cli/index.js", "serve"],
      "env": {
        "YOUTUBE_MCP_PROFILE": "default",
        "YOUTUBE_API_KEY": "your-api-key"
      }
    }
  }
}

Codex

[mcp_servers.youtube]
command = "node"
args = ["/absolute/path/to/Youtube MCP/dist/cli/index.js", "serve"]

[mcp_servers.youtube.env]
YOUTUBE_MCP_PROFILE = "default"
YOUTUBE_API_KEY = "your-api-key"

Führe nach dem Ziehen von Änderungen npm run build erneut aus; Clients führen die kompilierte dist-Ausgabe aus, nicht src.

Die Google-Autorisierung für diesen lokalen Server erfolgt über die eigenen setup- und login-Befehle. MCP-Login-Befehle auf Client-Ebene ersetzen den nachgelagerten Google-OAuth-Ablauf nicht.

Client-Konfiguration nach der Veröffentlichung

Sobald das Paket veröffentlicht ist, fixiere eine veröffentlichte Version anstelle von latest, damit ein MCP-Client das Verhalten nicht unerwartet ändern kann.

Claude Desktop

{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "@youtube-mcp/server@0.4.0", "serve"],
      "env": {
        "YOUTUBE_MCP_PROFILE": "default"
      }
    }
  }
}

Unter nativem Windows verwende "command": "cmd" und stell den Argumenten "/c", "npx" voran.

Claude Code

claude mcp add youtube --scope user \
  --env YOUTUBE_MCP_PROFILE=default -- \
  npx -y @youtube-mcp/server@0.4.0 serve

Codex

codex mcp add youtube \
  --env YOUTUBE_MCP_PROFILE=default -- \
  npx -y @youtube-mcp/server@0.4.0 serve

Äquivalente Codex-Konfiguration:

[mcp_servers.youtube]
command = "npx"
args = ["-y", "@youtube-mcp/server@0.4.0", "serve"]

[mcp_servers.youtube.env]
YOUTUBE_MCP_PROFILE = "default"

Wie viel auf einmal hinzugefügt werden kann

Feste Schema-Grenzen pro Tool-Aufruf:

50 Songs sind also die Obergrenze für eine Playlist-Erstellung. Da ein vorbereiteter Entwurf noch nicht in eine bestehende Playlist übernommen werden kann, muss eine Liste mit mehr als 50 Songs auf mehr als eine Playlist aufgeteilt werden.

In der Praxis ist das Tageskontingent die engere Grenze. Bei Googles Standard von 10.000 Einheiten pro Projekt und Tag kostet ein Durchlauf mit 50 Songs ungefähr:

Das bedeutet grob eine Playlist mit 50 Songs pro Projekt und Tag. Ein zweiter vollständiger Lauf am selben Tag erschöpft das Kontingent und schlägt mitten in der Einfügung fehl. Dieselbe Liste zweimal vorzubereiten ist besonders teuer: Die Suchen werden erneut berechnet, obwohl die Antworten unverändert sind.

Das Kontingent wird um Mitternacht US-pazifischer Zeit zurückgesetzt; dies ist die Tagesgrenze, die das lokale Journal verwendet.

Kontingent-Erwartungen

youtube_quota_status meldet lokal beobachtete Nutzung, keinen maßgeblichen Google-Kontostand. Allgemeine Einheiten und search.list-Aufrufe werden getrennt erfasst, weil Google eine separate standardmäßige tägliche Grenze für Suchaufrufe anwendet.

[!WARNING] Bekannte Einschränkung: Das lokale Journal erfasst jeden search.list als 1 allgemeine Einheit plus 1 Suchaufruf, während Google 100 Einheiten dafür berechnet. Nach intensiver Suche unterschätzt general_units daher den tatsächlichen Verbrauch um 99 Einheiten pro Suche, und ein Schreibvorgang kann wegen des Kontingents abgelehnt werden, obwohl der gemeldete Wert noch niedrig aussieht. Behandeln Sie den search_calls-Zähler bis zur Korrektur als das aussagekräftige Signal. Vorschauen zeigen weiterhin einen estimated_commit_units-Wert für den Schreibteil eines Commits.

Kontingentwerte können sich ändern. Implementierungs- und Release-Arbeit muss die aktuelle offizielle Kostentabelle verifizieren, anstatt Werte in dieser README als dauerhafte Konstanten zu behandeln.

Fehlerbehebung

Ein Commit meldet status: "partial" mit leerem completed und allem in pending. Die Playlist wurde erstellt, aber der erste Einfügevorgang wurde abgelehnt – meist wegen des täglichen Kontingents. Es wird nichts blind wiederholt, daher werden keine doppelten Einträge geschrieben. Prüfen Sie youtube_quota_status, löschen Sie die leere Playlist und führen Sie den Vorgang nach dem Reset zur US-pazifischen Zeit erneut aus. Da ein Entwurf nur einmal verwendet werden kann, erfordert die erneute Ausführung einen frischen youtube_prepare_music_playlist.

login schlägt fehl, bevor sich ein Browser öffnet. Für das Profil ist kein Client-Secret gespeichert. Führen Sie zuerst setup aus und bestätigen Sie, dass Sie sich auf dem vorgesehenen YOUTUBE_MCP_PROFILE befinden.

Die Autorisierung gelingt, funktioniert aber etwa eine Woche später nicht mehr. Google-OAuth-Projekte im Status „Testing“ stellen Refresh-Tokens aus, die nach sieben Tagen ablaufen. Veröffentlichen Sie den Zustimmungsbildschirm oder führen Sie login erneut aus.

403 bei einem öffentlichen Lesezugriff. YOUTUBE_API_KEY fehlt in der Umgebung des Servers. Er wird nie dauerhaft gespeichert, daher muss er bei jedem Start vorhanden sein – einschließlich des env-Blocks der MCP-Client-Konfiguration.

Authentifizierungsmodell

• Öffentliche Lesezugriffe erfordern YOUTUBE_API_KEY in der Prozessumgebung.

• Konten-Lesezugriffe erfordern OAuth mit dem youtube.readonly-Scope.

• Die Playlist-Erstellung erfordert youtube.force-ssl, da Google keinen Playlist-only-Scope bereitstellt.

• Der Server begegnet diesem breiten Google-Scope mit einer strengen Endpunkt-Allowlist: Nur Schreib-Endpunkte für Playlists und Playlist-Elemente sind aufrufbar.

• Installierte Anwendungen verwenden Authorization Code + PKCE, einen zufälligen state und eine Loopback-Weiterleitung auf 127.0.0.1 mit einem zufälligen Port.

• Dienstkonten werden für normale YouTube-Konten nicht unterstützt.

Committen Sie niemals API-Schlüssel, OAuth-Clientdaten, Zugriffstokens, Refresh-Tokens, lokale Datenbanken, Debug-Protokolle oder .env-Dateien.

Untertitel und Analysen

Der allgemeine Abruf öffentlicher Transkripte ist nicht Teil von v1. Der offizielle Endpunkt zum Herunterladen von Untertiteln ist berechtigungsgeschützt und teuer, daher wird kein inoffizielles Scraping verwendet. Eine vom Eigentümer autorisierte Untertitelverwaltung kann später in Betracht gezogen werden.

Die YouTube-Analytics- und Reporting-APIs werden ebenfalls zurückgestellt. Sie erfordern eine separate OAuth-Autorisierung, eigene Datenmodelle und ein eigenes Betriebsverhalten und sollten den zunächst auf Playlists fokussierten Server nicht verkomplizieren.

Entwicklung

Der implementierte Stack ist TypeScript, Node.js 20.17+, ESM, das offizielle MCP-TypeScript-SDK, Zod-Validierung, direkte typisierte REST-Aufrufe an genehmigte Google-Endpunkte, SQLite für den lokalen Kontingent-/Entwurfs-/Journalstatus und einen OS-Keychain-Adapter für OAuth-Refresh-Tokens.

Aktuelle Prüfungen:

npm run format:check
npm run lint
npm run typecheck
npm test
npm run build

Die Implementierung sollte den Phasen und Abnahmetoren in PLAN.md folgen. Agentspezifische Einschränkungen und Done-Definitionen sind in AGENTS.md. Claude Code sollte mit CLAUDE.md beginnen.

Projektstatus

• Produkt- und Sicherheitsarchitektur

• Repository-Entwicklungsanweisungen

• TypeScript-Paketgerüst

• Öffentliche Lesetools

• OAuth und Profile

• Musikabgleich und Vorschau

• Bestätigte Erstellung neuer Playlists

• In der Vorschau gezeigte Playlist-Aktualisierung, -Umordnung, -Entfernung und -Löschung

• Bestehende Playlist als Ziel für Musik-Entwurfs-Commits

• Korrekte search.list-Verbuchung allgemeiner Einheiten im Kontingent-Journal

• Clientübergreifende Integrationstests

• Erste npm-Veröffentlichung

Lizenz

Lizenziert unter der Apache-Lizenz 2.0. Der vollständige Lizenztext befindet sich in LICENSE.

Referenzen

• Model Context Protocol

• YouTube Data API v3

• Kontingentkosten der YouTube Data API

• Google OAuth für installierte Apps

• Claude-MCP-Dokumentation

• Codex-MCP-Dokumentation