YouTube MCP Server

Ein Open-Source-Model-Context-Protocol-Server (MCP) zur Nutzung von YouTube über MCP-Clients wie Claude Desktop, Claude Code und Codex.

Der primäre Arbeitsablauf ist:

1. Geben Sie einem MCP-Client eine Liste von Songs.

2. Prüfen Sie die bewerteten YouTube-Treffer, bevor etwas geändert wird.

3. Erstellen Sie 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.

[!WICHTIG] Das TypeScript-Paket, der stdio-Server, öffentliche und authentifizierte Lesevorgänge, PKCE-OAuth, Musikvorbereitung, bestätigte Erstellung neuer Playlists und vollständig in der Vorschau angezeigte Playlist-Änderungen sind implementiert und getestet. Ein vorbereiteter Musiksatz kann in eine neue Playlist übernommen oder an eine bestehende eigene Playlist angehängt werden.

Designziele

• Sichere Playlist-Schreibvorgänge mit Vorschau-vor-Übernahme-Semantik.

• Nur offizielle YouTube Data API v3-Endpunkte.

• Bring-your-own-Google-OAuth-Client; das Projekt liefert niemals gemeinsame Google-Anmeldedaten.

• Geheimnisse werden wann immer möglich im Betriebssystem-Schlüsselbund gespeichert.

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

• Lokaler stdio-Transport für 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.

Related MCP server: youtube-music-mcp

Geplanter v1-Umfang

Lesetools

• 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 Titel pro Vorbereitungsanfrage akzeptieren.

• Wahrscheinliche YouTube-Musikvideo-Treffer suchen und bewerten.

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

• Ausdrücklich ausgewählte Treffer in eine neue Playlist oder eine bestehende eigene Playlist übernehmen.

• Neue Playlists standardmäßig auf private setzen.

Kommentarverwaltung

• Einen Top-Level-Kommentar zu einem Video posten oder auf einen vorhandenen Kommentar antworten.

• Einen Kommentar löschen oder seinen Moderationsstatus hinter einer Vorschau und einem einmaligen Handle festlegen.

• Verwendet den bereits für Playlist-Schreibvorgänge angeforderten Bereich youtube.force-ssl, sodass keine zusätzliche Zustimmung erforderlich ist.

Playlist-Verwaltung

• Playlists erstellen und Videos hinzufügen.

• Playlist-Metadaten oder Datenschutz aktualisieren.

• Playlist-Elemente neu anordnen oder entfernen.

• Playlists nach Ausstellung eines kurzlebigen, einmaligen Bestätigungs-Handles löschen.

Playlist-Aktualisierungen, Elemententfernung/-neuordnung und Löschung verwenden zwei Tools: youtube_prepare_playlist_mutation gibt den genauen Diff und ein 10-Minuten-Handle zurück, ohne zu schreiben; youtube_apply_playlist_mutation überprüft erneut den Besitz und die Playlist-Snapshot, bevor dieses Handle einmal verbraucht wird.

Video-Upload und Lebenszyklus

• Eine lokale Videodatei über einen fortsetzbaren Upload hochladen, standardmäßig auf private.

• Titel, Beschreibung, Tags oder Datenschutz eines eigenen Videos aktualisieren. Nicht angegebene Felder werden übernommen und nicht gelöscht.

• Ein benutzerdefiniertes Thumbnail aus einem lokalen JPEG oder PNG festlegen.

• Ein eigenes Video in der Vorschau anzeigen und dann dauerhaft löschen.

Video-Schreibvorgänge erfordern den zusätzlichen Bereich youtube.upload und lehnen es rundweg ab, wenn ein Profil ohne diesen Bereich autorisiert wurde. youtube_plan_video_upload validiert die Datei und meldet die Kosten, ohne YouTube zu kontaktieren, da videos.insert 1600 Einheiten kostet – etwa 16 % eines standardmäßigen Tagesbudgets pro Upload. Ein Upload wird niemals wiederholt: Wenn das Ergebnis unbekannt ist, wird dies gemeldet, damit Sie nach einem Teil-Upload suchen können, anstatt ein Duplikat zu veröffentlichen.

Playlist-, Kommentar- und Videoverwaltung sind die implementierten Schreibflächen. Analytik-Berichte (0.8) stehen auf der Roadmap und sind noch nicht aufrufbar. Bewertungen, Abonnements und Kanal-Einstellungs-Schreibvorgänge bleiben dauerhaft außerhalb des Umfangs.

Einrichtung

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

Schritt 1 — Prüfen Sie auf Node.js und npm

node -v
npm -v

Wenn node -v v20.17 oder neuer ausgibt und npm -v eine Version ausgibt, überspringen Sie zu Schritt 3. Wenn einer der Befehle "command not found" meldet, fahren Sie mit Schritt 2 fort.

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

npm wird mit Node.js geliefert; die Installation von Node installiert beide. Wählen Sie eine Zeile für Ihre Plattform und führen Sie dann Schritt 1 erneut aus, um zu bestätigen.

Wenn Sie Node nicht systemweit installieren möchten oder mehrere Node-Versionen nebeneinander benötigen, verwenden Sie 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 Äquivalent nvm-windows: nvm install 22 und dann nvm use 22.

Schließen und öffnen Sie das Terminal nach der Installation erneut und führen Sie dann node -v und npm -v erneut aus.

Schritt 3 — Abhängigkeiten installieren und erstellen

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

npm ci installiert die exakten Versionen in package-lock.json; verwenden Sie npm install nur, wenn Sie Abhängigkeiten ändern möchten. Der Build schreibt die ausführbare Datei nach dist/cli/index.js, die jeder untenstehende Befehl aufruft.

Überprüfen Sie den Build und das lokale Datenverzeichnis:

node dist/cli/index.js doctor

Schritt 4 — Die Google-Anmeldedaten erstellen

Alles unten stammt aus Ihrem eigenen Google Cloud-Projekt. Dieses Projekt liefert niemals gemeinsame Google-Anmeldedaten.

1. Erstellen oder wählen Sie ein Projekt in der Google Cloud-Konsole.

2. Aktivieren Sie YouTube Data API v3 für dieses Projekt.

3. Erstellen Sie einen API-Schlüssel (Anmeldedaten → Anmeldedaten erstellen → API-Schlüssel). Dies deckt öffentliche Lesevorgänge ab.

4. Konfigurieren Sie den OAuth-Zustimmungsbildschirm. Solange das Projekt den Status "Test" hat, fügen Sie Ihr eigenes Google-Konto unter Testbenutzer hinzu, sonst wird login verweigert.

5. Erstellen Sie einen OAuth-Client vom Typ Desktop-App und kopieren Sie dann sowohl seine Client-ID als auch sein Client-Geheimnis.

Google verlangt client_secret im Autorisierungscode-Austausch auch für installierte Anwendungen, daher ergänzt PKCE hier das Geheimnis, anstatt es zu ersetzen.

Schritt 5 — Die Anmeldedaten, die der Server benötigt

Es gibt insgesamt vier Anmeldedaten. Sie liefern die ersten drei; die vierte wird für Sie von login erhalten.

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

Fügen Sie niemals eine dieser Angaben in eine Chat-Nachricht, eine gemeinsame MCP-Konfigurationsdatei oder einen Befehl ein, der committet wird. Bevorzugen Sie die interaktiven Eingabeaufforderungen oder das Umgebungs-/Geheimnis-Injektionsfeld Ihres Clients.

Schritt 6 — Setup ausführen, dann anmelden

Führen Sie diese in der Reihenfolge aus. setup überschreibt die gespeicherten Bereiche und die Kanalidentität des Profils. Wenn Sie es nach login ausführen, 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 Geheimnis ganz aus dem Shell-Verlauf oder der Prozessliste herauszuhalten, lassen Sie beide Variablen weg und lassen Sie setup danach fragen:

node dist/cli/index.js setup

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

login öffnet die Google-Autorisierungsseite und kehrt über einen zufälligen Loopback-Port auf 127.0.0.1 zurück, unter Verwendung von PKCE S256 und einem zufälligen Statuswert. Es schlägt sofort fehl, bevor ein Browser geöffnet wird, wenn kein Client-Geheimnis für das Profil gespeichert ist.

Um die gespeicherten Anmeldedaten 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, daher wird er normalerweise von einem Client gestartet und nicht von Hand. Verfügbare Befehle sind serve, doctor, status, setup, login und logout.

Lokaler Datenspeicherort

Profile, das Quota-Ledger, Entwürfe und Operationsjournale befinden sich in einem 0700-Verzeichnis:

Überschreiben Sie mit YOUTUBE_MCP_DATA_DIR. Um den gesamten lokalen Zustand zu entfernen, führen Sie logout aus und löschen Sie dann dieses Verzeichnis. Schlüsselbund-Einträge werden von logout entfernt.

Verbinden eines Clients mit dem lokalen Build

Bis das Paket veröffentlicht ist, weisen Sie Clients auf den absoluten Pfad Ihrer erstellten dist/cli/index.js hin.

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ühren Sie npm run build nach dem Ziehen von Änderungen erneut aus; Clients führen die kompilierte dist-Ausgabe aus, nicht src.

Die Google-Autorisierung für diesen lokalen Server wird von seinen eigenen setup- und login-Befehlen durchgeführt. Client-seitige MCP-Login-Befehle ersetzen nicht den nachgelagerten Google-OAuth-Fluss.

Client-Konfiguration nach der Veröffentlichung

Sobald das Paket veröffentlicht ist, pinnen Sie eine veröffentlichte Version an, anstatt latest zu verwenden, damit ein MCP-Client das Verhalten nicht unerwartet ändern kann.

Claude Desktop

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

Unter nativem Windows verwenden Sie "command": "cmd" und stellen den Argumenten "/c", "npx" voran.

Claude Code

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

Codex

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

Äquivalente Codex-Konfiguration:

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

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

Wie viel auf einmal hinzugefügt werden kann

Harte Schema-Limits pro Tool-Aufruf:

50 Songs sind also die Obergrenze für einen einzelnen Commit. Eine längere Liste wird durch Commits in Batches von 50 verarbeitet: Die Playlist wird mit dem ersten Batch erstellt, dann wird bei jedem weiteren Commit deren target_playlist_id übergeben, um anzuhängen. Bereits vorhandene Duplikate werden übersprungen und gemeldet, statt doppelt eingefügt zu werden.

Das tägliche Kontingent ist in der Praxis die engere Grenze. Gegenüber Googles Standard von 10.000 Einheiten pro Projekt und Tag kostet ein Durchlauf mit 50 Songs ungefähr:

Das bedeutet ungefähr eine 50-Song-Playlist pro Projekt und Tag. Ein zweiter vollständiger Durchlauf am selben Tag erschöpft das Kontingent und schlägt mitten im Einfügen fehl. Das zweimalige Vorbereiten derselben Liste ist besonders teuer: Die Suchanfragen werden erneut berechnet, obwohl die Antworten unverändert sind.

Das Kontingent wird um Mitternacht US-Pazifikzeit zurückgesetzt, was die Tagesgrenze ist, die das lokale Hauptbuch verwendet.

Kontingenterwartungen

youtube_quota_status meldet lokal beobachtete Nutzung, nicht einen maßgeblichen Google-Saldo. Allgemeine Einheiten und search.list-Aufrufe werden getrennt erfasst, weil Google ein separates standardmäßiges Tageslimit für Suchaufrufe anwendet.

search.list wird mit den veröffentlichten 100 Einheiten abgerechnet, daher spiegelt general_units den tatsächlichen Verbrauch wider. Versionen vor 0.5.0 erfassten es als 1 Einheit und unterschätzten die Nutzung dadurch um 99 Einheiten pro Suche; ein Schreibvorgang konnte wegen des Kontingents abgelehnt werden, während der gemeldete Wert noch niedrig aussah. Aktualisieren Sie, wenn Sie einen älteren Build verwenden.

Kontingentwerte können sich ändern. Implementierungs- und Release-Arbeit muss die aktuelle offizielle Kostentabelle überprüfen, statt 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 Insert wurde abgelehnt – meistens wegen des Tageskontingents. Es wird nichts blind wiederholt, daher werden keine doppelten Elemente geschrieben. Prüfen Sie youtube_quota_status, löschen Sie die leere Playlist und führen Sie den Vorgang nach dem Pazifikzeit-Reset erneut aus. Da ein Entwurf nur einmal verwendet werden kann, erfordert ein erneuter Durchlauf ein frisches 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 stellen Sie sicher, dass Sie das beabsichtigte YOUTUBE_MCP_PROFILE verwenden.

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.

• Kontobezogene Lesezugriffe erfordern OAuth mit dem Bereich youtube.readonly.

• Playlist-Erstellung und Kommentar-Schreibvorgänge erfordern youtube.force-ssl, weil Google keinen reinen Playlist-Bereich bereitstellt.

• Video-Upload und Lebenszyklus erfordern youtube.upload. Er wird separat angefordert, und Video-Tools verweigern die Arbeit, wenn ein Profil ohne ihn autorisiert wurde. Fügen Sie ihn zu Ihrem Zustimmungsbildschirm hinzu und führen Sie vor dem Hochladen login erneut aus.

• Der Server wirkt dem breiten Google-Bereich mit einer strengen Endpunkt-Allowlist entgegen: Nur Playlist- und Playlist-Element-Schreibendpunkte sind aufrufbar.

• Installierte Anwendungen verwenden Authorization Code + PKCE, ein zufälliges state und eine Loopback-Umleitung 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-Client-Daten, Zugriffstokens, Refresh-Tokens, lokale Datenbanken, Debug-Protokolle oder .env-Dateien.

Untertitel und Analysen

Der allgemeine öffentliche Transkriptabruf ist nicht Teil von v1. Der offizielle Untertitel-Download-Endpunkt 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 sind ebenfalls aufgeschoben. Sie erfordern separate OAuth-, Datenmodelle und Betriebsverhalten und sollten den anfänglichen playlist-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 lokalen Kontingent-/Entwurfs-/Journal-Status und ein 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 Akzeptanzkriterien in PLAN.md folgen. Agentspezifische Einschränkungen und Definitionen von „fertig" finden Sie in AGENTS.md. Claude Code sollte mit CLAUDE.md beginnen.

Projektstatus

• Produkt- und Sicherheitsarchitektur

• Repository-Entwicklungsanweisungen

• TypeScript-Paketgerüst

• Öffentliche Lesetools

• OAuth und Profile

• Musikkennzeichnung und Vorschau

• Bestätigte Erstellung neuer Playlists

• Vorgeschautes Playlist-Update, Umsortierung, Entfernung und Löschung

• Ziel für bestehende Playlists für Musikentwurfs-Commits (0.5)

• Korrekte search.list-Allgemeineinheiten-Buchführung im Kontingent-Hauptbuch (0.5)

• Kommentar-Einfügen, Antworten, Löschen und Moderation (0.6)

• Video-Upload, Metadaten-Update, Löschen und Thumbnails (0.7)

• YouTube-Analytics-Berichte (0.8)

• Clientübergreifende Integrationstests

• Erste npm-Veröffentlichung

Lizenz

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

Referenzen

• Model Context Protocol

• YouTube Data API v3

• YouTube Data API-Kontingentkosten

• Google OAuth für installierte Apps

• Claude-MCP-Dokumentation

• Codex-MCP-Dokumentation