Edutube MCP

🌐 Projektseite (GitHub Pages): https://engmohammeda.github.io/edutube-mcp/ — enthält einen Live-Explorer für echte extrahierte Lektionen.

Verwandle YouTube-Playlists und -Videos in strukturierte Lektionen, Analysen, Frames und Quizze — mit Google Gemini und automatischer Modellrotation.

MCP-stdio-Server + CLI für KI-Agenten und LMS-Pipelines. Füge eine Playlist-URL ein und erhalte pro Lektion JSON: wörtlicher Dialog mit arabischen Übersetzungen, Schlüsselausdrücke, Vokabular, kulturelle/Aussprache-Hinweise und ein Quiz mit 10 Fragen — extrahiert aus dem tatsächlichen Audio und den visuellen Inhalten, nicht nur aus Untertiteln.

playlist URL ──▶ Edutube ──▶ lesson-01.json … lesson-NN.json + lessons-all.json

Features

• Playlist-Import per URL — füge eine beliebige YouTube-Playlist-URL (oder Playlist-ID oder eine einzelne Video-URL) ein. Einträge werden über die YouTube Data API aufgelöst, wenn YOUTUBE_API_KEY gesetzt ist, andernfalls automatisch über yt-dlp --flat-playlist (kein zusätzlicher Schlüssel erforderlich).

• Strukturierte Lektionsextraktion — integriertes LMS-Schema (dialogue / key_expressions / global_vocabulary / lesson_notes / quiz) mit einer Option für ein benutzerdefiniertes Schema für dein eigenes Format.

• Pipeline für lange Videos mit Fenster-Fallback — zuerst ein Durchlauf über das gesamte Video; falls das fehlschlägt (Kontingent, Fristen, sehr lange VODs), wechselt es automatisch zur Fensterextraktion mit 150-Sekunden-Fenstern, inklusive Zusammenführung und Deduplizierung.

• Automatische Modellrotation — jedes Gemini-Modell hat seinen eigenen Kontingentpool im kostenlosen Tarif. Bei 429 RESOURCE_EXHAUSTED wird dieselbe Anfrage transparent auf dem nächsten verfügbaren Modell wiederholt. Der Modellkatalog wird live von der Gemini-API abgerufen, sodass neue Modelle (z. B. gemini-3.6-flash, gemini-3.7-*) ohne Codeänderungen in die Rotation aufgenommen werden.

• Multimodale Analysetools — analyze_youtube_video (Audio + visuelle Inhalte), analyze_youtube_video_audio (sprachbasiert), exakte JPEG-Frame-Extraktion mit yt-dlp + ffmpeg, Metadaten über die YouTube Data API.

• Lange VODs & Sitzungen — aufgabenbasiertes analyze_long_youtube_video, wiederverwendbare sessionId-Folgefragen und Kompatibilitäts-Hintergrundjobs (start_long_youtube_analysis → poll → result → cancel).

• Fortsetzbare Stapel — bereits gültige Lektionsdateien werden übersprungen; unterbrochene Läufe werden an der Stelle fortgesetzt, an der sie gestoppt wurden.

• CLI-Modus — edutube-mcp extract <url> funktioniert ohne MCP-Client.

Related MCP server: YT-NINJA

Requirements

• Node.js ≥ 20

• Ein Google-Gemini-API-Schlüssel (GEMINI_API_KEY)

• Optional: YOUTUBE_API_KEY (Metadaten-Tool + schnellerer Playlist-Import)

• Optional, aber empfohlen: yt-dlp und ffmpeg im PATH (oder YT_DLP_PATH)

Quick Start (MCP client)

{
  "mcpServers": {
    "edutube": {
      "command": "npx",
      "args": ["-y", "@engmohammeda/edutube-mcp"],
      "env": {
        "GEMINI_API_KEY": "your_gemini_key_here",
        "YOUTUBE_API_KEY": "optional_youtube_key_here"
      }
    }
  }
}

Aus dem Quellcode:

git clone https://github.com/engmohammeda/edutube-mcp.git
cd edutube-mcp
npm install && npm run build
cp .env.example .env   # fill GEMINI_API_KEY
npm start              # MCP stdio server

Quick Start (CLI)

# extract a whole playlist into ./edutube-output
edutube-mcp extract "https://www.youtube.com/playlist?list=PL..." --out ./edutube-output --max 20

# or a single video
edutube-mcp extract "https://www.youtube.com/watch?v=VIDEO_ID" --out ./lessons

Stdout ist sauberes JSON (Fortschritt geht an stderr), sodass es direkt in Skripte und LMS-Importeure geleitet werden kann.

Tools (15)

Configuration

Client Integrations

Claude Code

claude mcp add edutube --transport stdio -- node /path/to/edutube-mcp/dist/index.js

Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "edutube": {
      "command": "node",
      "args": ["/path/to/edutube-mcp/dist/index.js"],
      "env": { "GEMINI_API_KEY": "..." }
    }
  }
}

Codex (~/.codex/config.toml)

[mcp_servers.edutube]
command = "node"
args = ["/path/to/edutube-mcp/dist/index.js"]
env = { GEMINI_API_KEY = "..." }

Documentation

• Installation

• Konfiguration

• Werkzeuge

• Playlist-Lektionen (Edutube-Pipeline)

• Modellrotation

• CLI

• Lange Videos

• Changelog

Privacy & Limits

Medien, URLs und Prompts werden an Google Gemini gesendet. Schlüssel im kostenlosen Tarif haben kleine tägliche Kontingente pro Modell (~20 Anfragen/Tag/Modell); die automatische Rotation verteilt die Arbeit auf alle Modelle deines Schlüssels. Für Produktionsstapel verwende einen kostenpflichtigen (Pay-as-you-go-)Schlüssel. Private, altersbeschränkte, DRM- oder regionsgesperrte Videos können fehlschlagen. Du bist dafür verantwortlich, die Bedingungen von YouTube und Gemini einzuhalten.

License

MIT — siehe LICENSE.

العربية

Edutube MCP — حوِّل قوائم تشغيل وفيديوهات يوتيوب إلى دروس مهيكلة جاهزة للاستيراد في LMS: حوار كامل مع الترجمة العربية، التعبيرات المفتاحية، المفردات مع أمثلة إلزامية، ملاحظات ثقافية/نطق بالعربية، واختبار من 10 أسئلة بأنواع متعددة — مستخرج من الصوت والصورة فعليًا وليس من الترجمة النصية فقط.

أبرز الميزات:

• استيراد قائمة تشغيل بلصق الرابط فقط عبر أداة start_edutube_extraction (أو أمر CLI edutube-mcp extract)، مع استئناف تلقائي يتخطى الدروس المكتملة.

• تدوير تلقائي بين نماذج Gemini: عند استنفاد حصة أي نموذج (429) يُعاد الطلب على النموذج التالي تلقائيًا، مع اكتشاف ديناميكي لأي نماذج جديدة متاحة لمفتاحك.

• مسار فيديو طويل + بديل نوافذ 150 ثانية عند الفشل، ودمج وإزالة تكرار.

• 15 أداة MCP تشمل التحليل متعدد الوسائط، استخراج إطارات JPEG دقيقة، البيانات الوصفية، والوظائف الخلفية للعملاء ذات المهل الثابتة.

التشغيل السريع: انسخ .env.example إلى .env وضع GEMINI_API_KEY، ثم npm install && npm run build && npm start، أو استخدم الـCLI مباشرة. راجع التوثيق أعلاه للتفاصيل والربط مع Claude Code وCursor وCodex.