YouTube Video Analyzer MCP

MCP-stdio-Server zur Analyse öffentlicher YouTube-Videos mit Google Gemini.

Verwenden Sie ihn mit jedem MCP-kompatiblen Client, um Videos zusammenzufassen, zeitgestempelte Erkenntnisse zu extrahieren, gesprochene Inhalte zu analysieren, Metadaten zu prüfen, mit langen VODs zu arbeiten und Folgefragen zu wiederverwendbaren Langvideo-Sitzungen zu stellen.

Was er kann

• Analysiert öffentliche YouTube-Videos mit Gemini.

• Analysiert sprachfokussierte Videos mit Audio-First-Anweisungen.

• Ruft normalisierte YouTube-Metadaten über die YouTube Data API ab.

• Extrahiert hochauflösende JPEG-Frames aus YouTube-Videos mit yt-dlp und ffmpeg.

• Analysiert lange Videos und VODs über erforderliche MCP-Tasks.

• Analysiert lange Videos und VODs über Kompatibilitäts-Hintergrundjobs für Clients ohne MCP-Task-Unterstützung.

• Wiederverwendet Langvideo-Sitzungen für Folgefragen.

• Fällt auf URL-Chunking zurück, wenn lokale Download-Tools nicht verfügbar sind.

• Gibt strukturiertes JSON zurück, wenn Sie ein benutzerdefiniertes Antwort-Schema bereitstellen.

Related MCP server: YT-NINJA

Anforderungen

• Node.js 20 oder neuer.

• Ein Gemini-API-Schlüssel.

• Optional: ein YouTube-Data-API-Schlüssel für die Metadatensuche.

• Optional für beste Langvideo-Unterstützung: yt-dlp und ffmpeg.

Schnellstart

Verwenden Sie das veröffentlichte Paket direkt von Ihrem MCP-Client mit npx:

{
  "mcpServers": {
    "youtube-analyzer": {
      "command": "npx",
      "args": ["-y", "@ludylops/youtube-video-analyzer-mcp"],
      "env": {
        "GEMINI_API_KEY": "your_gemini_key_here",
        "YOUTUBE_API_KEY": "optional_youtube_key_here"
      }
    }
  }
}

GEMINI_API_KEY ist erforderlich. YOUTUBE_API_KEY wird nur für get_youtube_video_metadata benötigt.

Globale Einrichtung

Sie können das Paket auch global installieren und wiederverwendbare Konfiguration speichern:

npm install -g @ludylops/youtube-video-analyzer-mcp
youtube-video-analyzer-mcp setup

Dann kann Ihr MCP-Client Folgendes verwenden:

{
  "mcpServers": {
    "youtube-analyzer": {
      "command": "youtube-video-analyzer-mcp"
    }
  }
}

Pakete

Dieses Repository ist ein kleines npm-Workspace:

• @ludylops/video-analysis-core: wiederverwendbare transportagnostische Videoanalyse-Logik in packages/video-analysis-core.

• @ludylops/youtube-video-analyzer-mcp: MCP-stdio-Server-Adapter im Repository-Stammverzeichnis.

Der MCP-Server hängt vom Core-Paket ab, sodass SaaS-Apps, CLIs, Skills und andere Integrationen dieselbe Analyselogik wiederverwenden können, ohne von MCP abzuhängen.

Lokale Entwicklung

npm install
npm run build
npm test
npm start

Kopieren Sie .env.example nach .env für lokale Ausführungen:

GEMINI_API_KEY=your_gemini_api_key_here
YOUTUBE_API_KEY=your_youtube_api_key_here
GEMINI_MODEL=gemini-2.5-pro
YT_DLP_PATH=yt-dlp
MCP_LOG_LEVEL=warn

Tools

• get_youtube_analyzer_capabilities: prüft die lokale Unterstützung für Langvideo-Strategien.

• get_youtube_video_metadata: ruft normalisierte öffentliche YouTube-Metadaten ab.

• get_youtube_video_frame: extrahiert ein hochauflösendes JPEG-Frame zu einem Zeitstempel, mit optionaler Gemini-Zeitstempel-Verfeinerung vor der lokalen Extraktion.

• analyze_youtube_video: analysiert kurze Videos oder begrenzte Clip-Fenster.

• analyze_youtube_video_audio: analysiert sprachfokussierte Videos mit Audio-First-Anweisungen.

• analyze_long_youtube_video: analysiert lange Videos oder VODs als erforderlichen MCP-Task.

• start_long_youtube_analysis: startet einen Hintergrund-Langvideo-Job und gibt eine jobId zurück.

• get_long_youtube_analysis_status: fragt einen Hintergrund-Langvideo-Job ab.

• get_long_youtube_analysis_result: ruft das Ergebnis eines abgeschlossenen Hintergrund-Langvideo-Jobs ab.

• cancel_long_youtube_analysis: bricht einen Hintergrund-Langvideo-Job ab.

• continue_long_video_analysis: stellt Folgefragen zu einer früheren Langvideo-Sitzung als erforderlichen MCP-Task.

Detaillierte Eingaben, Strategien und Beispiele finden Sie in docs/tools.md.

Lange Videos

Rufen Sie für VODs und lange Videos zuerst get_youtube_analyzer_capabilities auf.

Die nativen Langvideo-Tools erfordern die Ausführung von MCP-Tasks. Wenn Ihr Client nur synchrone Tool-Aufrufe mit einem festen Timeout wie 120 Sekunden unterstützt, verwenden Sie den Kompatibilitäts-Job-Workflow: start_long_youtube_analysis, fragen Sie get_long_youtube_analysis_status ab und rufen Sie dann get_long_youtube_analysis_result ab. Sie können auch kürzere begrenzte Fenster mit analyze_youtube_video analysieren.

Wenn yt-dlp, ffmpeg und ein beschreibbares temporäres Verzeichnis verfügbar sind, verwenden Sie analyze_long_youtube_video mit strategy=auto oder strategy=uploaded_file. Dieser Pfad kann eine wiederverwendbare Gemini-Dateisitzung erstellen und eine sessionId zurückgeben.

Wenn lokale Download-Tools nicht verfügbar sind, verwenden Sie strategy=url_chunks. Dies vermeidet lokale Mediendownloads, kann aber mehr Gemini-Aufrufe erfordern.

Lesen Sie den vollständigen Leitfaden in docs/long-videos.md.

Dokumentation

• Installation

• Konfiguration

• Tools

• Lange Videos

• Beispiele

• Fehlerbehebung

• Release-Prozess

• Changelog

Datenschutz und Einschränkungen

Dieser Server sendet die YouTube-URL, Eingabeaufforderungen und relevante Medien oder abgeleitete Chunks an Google Gemini. Mit strategy=uploaded_file können lokale Tools temporäre Medien herunterladen, bevor sie an Gemini hochgeladen werden. get_youtube_video_frame lädt ein kleines temporäres hochwertiges Video-Fenster herunter und gibt ein exaktes JPEG-Frame zurück; wenn eine Zeitstempel-Verfeinerung angefordert wird, wird Gemini nur zur Auswahl eines Zeitstempels verwendet, nicht zur Erzeugung von Bildpixeln. Mit strategy=url_chunks vermeidet der Server lokale Mediendownloads, kann aber mehr Gemini-Aufrufe erfordern.

Private, gelöschte, altersbeschränkte, nur für Mitglieder zugängliche, DRM-geschützte oder regional gesperrte Videos können je nach YouTube- und Gemini-Zugriff fehlschlagen. Die Benutzer sind dafür verantwortlich, die YouTube-Bedingungen, die Gemini-API-Bedingungen, Urheberrechtsregeln und lokale Gesetze einzuhalten.

Projektstruktur

• packages/video-analysis-core/src: wiederverwendbarer Videoanalyse-Kern.

• src/server.ts: MCP-Server und Tool-Registrierung.

• src/mcp-server-main.ts: stdio-Transport-Einstiegspunkt.

• src/platform-runtime: Laufzeit-Adapter, die vom MCP-Server verwendet werden.

• bin/youtube-video-analyzer-mcp.js: CLI-Wrapper und Einrichtungsablauf.

• src/test: Testsuite.

Mitwirken

Beiträge sind willkommen. Beginnen Sie mit CONTRIBUTING.md, führen Sie vor Änderungen npm test aus und aktualisieren Sie CHANGELOG.md für sichtbare Verhaltensänderungen.

Lizenz

MIT. Siehe LICENSE.