YouTube MCP Server

Ein Python-basierter Model Context Protocol (MCP)-Server, der Bildungsinhalte aus YouTube-Videos extrahiert — Transkripte und visuell aussagekräftige Frames — und sie KI-Assistenten wie Claude, ChatGPT und jedem MCP-kompatiblen Client zur Verfügung stellt.

Was es tut

Gib einem KI-Assistenten eine YouTube-URL, und er kann:

1. Transkript lesen — Vollständige Untertitel mit Zeitstempeln, bereit für Zusammenfassungen, Q&A oder Inhaltsanalysen.

2. Video ansehen — Eine 5-Phasen-Computer-Vision-Pipeline extrahiert die informativsten Frames, bewertet sie nach Qualität, entfernt Duplikate und gibt sie als base64-codierte JPEGs zurück, die die KI „ansehen“ kann.

Kein manuelles Herunterladen. Kein Kopieren und Einfügen. Einfach eine URL einfügen und Fragen stellen.

Werkzeuge

get_transcript

Ruft die Untertitel des Videos mit youtube-transcript-api ab.

Parameter:

• url (erforderlich) — YouTube-Video-URL

• language (optional, Standard: "en") — Bevorzugte Untertitelsprache

• prefer_manual (optional, Standard: true) — Manuell erstellte Untertitel gegenüber automatisch erzeugten bevorzugen

Rückgabe: Ein sauberer, mit Zeitstempeln versehener Transkriptblock:

[00:00:00] So I want to start by offering you a free ...
[00:00:15] The key insight here is that ...

get_video_frames

Führt eine vollständige Videoanalyse-Pipeline aus, um die aussagekräftigsten visuellen Momente hervorzuheben.

Parameter:

• url (erforderlich) — YouTube-Video-URL

• max_frames (optional, Standard: 20) — Maximale Anzahl zurückzugebender Frames (Obergrenze: 40)

• scene_threshold (optional, Standard: 0.25) — Empfindlichkeit der FFmpeg-Szenenerkennung

• output_width (optional, Standard: 640) — Breite der zurückgegebenen JPEGs (proportionale Höhe)

• min_importance_score (optional, Standard: 0.35) — Mindestens erforderlicher zusammengesetzter Qualitätswert

Rückgabe:

• Metadaten: video_id, duration_seconds, pipeline_stats, fallback_used

• Frame-Blöcke: jeder enthält timestamp_ms, composite_score und ein base64-codiertes JPEG-Bild

• Ein Index, der jeden zurückgegebenen Frame mit Zeitstempel und Bewertung auflistet

Die Frame-Pipeline (5 Phasen)

Schnellstart

Voraussetzungen

• Python 3.11

• ffmpeg — Videoverarbeitung

• Tesseract OCR — Texterkennung in Frames

macOS:

brew install ffmpeg tesseract

Ubuntu / Linux:

sudo apt-get install ffmpeg tesseract-ocr tesseract-ocr-eng

Windows: Laden Sie ffmpeg und Tesseract herunter und fügen Sie beide zu Ihrem PATH hinzu.

Überprüfen:

ffmpeg -version
tesseract --version

Installation

# Clone the repository
git clone https://github.com/Ayush-Mamgain/youtube-mcp-server.git
cd youtube-mcp-server

# Create a virtual environment
python3 -m venv venv
source venv/bin/activate        # macOS / Linux
# venv\Scripts\activate      # Windows

# Install dependencies
pip install -r requirements.txt

Konfiguration

Erstellen Sie eine .env-Datei im Projektstammverzeichnis:

LOG_LEVEL=DEBUG
MCP_HTTP_PORT=8000

Optionale Anpassung (falls nicht angegeben, werden die Standardwerte aus config.py geladen):

Server starten

python server.py

Der Server startet unter http://localhost:8000.

Verbinden mit Claude.ai (lokal)

1. Starten Sie den Server: python server.py

2. Gehen Sie zu Claude.ai → Einstellungen → Integrationen → MCP-Server hinzufügen

3. Geben Sie ein: http://localhost:8000/mcp

Damit das in der Cloud gehostete Claude Ihren Server erreichen kann, müssen Sie ihn öffentlich zugänglich machen (siehe Bereitstellung unten).

API-Endpunkte

Projektstruktur

youtube-mcp-server/
├── server.py              # MCP entry point — FastMCP + Starlette HTTP server
├── config.py              # Loads and validates environment variables
├── logger.py              # stderr-only logging
├── url_parser.py          # Validates YouTube URLs and extracts video IDs
├── transcript.py          # Fetches captions via youtube-transcript-api
├── downloader.py          # Phase 1 — video download with yt-dlp
├── frame_extractor.py     # Phase 2 — scene-change frame extraction via ffmpeg
├── scorer.py              # Phase 3 — multi-signal frame scoring (OpenCV + Tesseract)
├── deduplicator.py        # Phase 4 — perceptual-hash deduplication
├── frame_loader.py        # Phase 5 — resize, JPEG encode, base64
├── video_frames.py        # Orchestrates Phases 1–5 with semaphore and cleanup
├── requirements.txt       # Pinned Python dependencies
└── .gitignore             # Excludes .env, venv, caches, test artifacts

Entwicklungsworkflow

Dieses Projekt wurde in 9 in sich abgeschlossenen Stufen entwickelt, jede mit eigener Testdatei und Verifikationsschritt:

Goldene Regel: Jede Stufe wird vor dem Fortfahren verifiziert. Führen Sie python test_stage{N}.py aus, um zu validieren.

Bereitstellung

Docker-Unterstützung ist geplant, aber noch nicht konfiguriert. Dieser Abschnitt wird aktualisiert, sobald die Containerisierung abgeschlossen ist.

Der Server läuft derzeit direkt auf jedem Rechner mit installiertem Python 3.11, ffmpeg und Tesseract. Empfohlene Hosting-Optionen, sobald Docker bereit ist:

• Railway

• Fly.io

• Render

Nach der Bereitstellung aktualisieren Sie die Integrations-URL in Claude.ai auf:

https://YOUR-DEPLOYMENT-URL/mcp

Design-Hinweise

• Die gesamte Protokollierung erfolgt ausschließlich über stderr. stdout ist ausschließlich für die MCP-Kommunikation reserviert.

• Thread-sicher: Die get_video_frames-Pipeline verwendet ein threading.Semaphore(1), um zu verhindern, dass gleichzeitige Downloads das System überlasten.

• Automatische Bereinigung: Temporäre Dateien, die während der Videoverarbeitung erstellt werden, werden nach jedem Durchlauf gelöscht.

• Strenge Validierung: Video-IDs werden gegen ^[A-Za-z0-9_-]{11}$ validiert. Reine Playlist-URLs, Kanal-URLs und fehlerhafte Eingaben werden mit klaren Fehlermeldungen abgelehnt.

• Sanfte Degradierung: Falls alle Frames unter dem Mindestwert für die Wichtigkeitsschwelle liegen, weicht die Pipeline auf die besten 5 Frames aus und setzt fallback_used: true.

Lizenz

MIT © Ayush Mamgain

Danksagungen

Erstellt mit FastMCP, Starlette, yt-dlp, youtube-transcript-api und OpenCV.