Edutube MCP

🌐 Project site (GitHub Pages): https://engmohammeda.github.io/edutube-mcp/ — includes a live explorer of real extracted lessons.

Turn YouTube playlists and videos into structured lessons, analyses, frames and quizzes — with Google Gemini and automatic model rotation.

MCP stdio server + CLI for AI agents and LMS pipelines. Paste a playlist URL and get back per-lesson JSON: verbatim dialogue with Arabic translations, key expressions, vocabulary, cultural/pronunciation notes, and a 10-question quiz — extracted from the actual audio and visuals, not just captions.

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

Features

• Playlist import by URL — paste any YouTube playlist URL (or playlist id, or a single video URL). Entries resolve via the YouTube Data API when YOUTUBE_API_KEY is set, otherwise automatically via yt-dlp --flat-playlist (no extra key needed).

• Structured lesson extraction — built-in LMS schema (dialogue / key_expressions / global_vocabulary / lesson_notes / quiz) with a custom-schema option for your own format.

• Long-video pipeline with windowed fallback — full-video pass first; if that fails (quota, deadlines, very long VODs) it automatically switches to 150-second windowed extraction with merge & dedupe.

• Automatic model rotation — every Gemini model has its own free-tier quota pool. On 429 RESOURCE_EXHAUSTED the same request transparently retries on the next available model. The model catalogue is discovered live from the Gemini API, so new models (e.g. gemini-3.6-flash, gemini-3.7-*) join the rotation without code changes.

• Multimodal analysis tools — analyze_youtube_video (audio + visuals), analyze_youtube_video_audio (speech-first), exact JPEG frame extraction with yt-dlp + ffmpeg, metadata via YouTube Data API.

• Long VODs & sessions — task-based analyze_long_youtube_video, reusable sessionId follow-ups, and compatibility background jobs (start_long_youtube_analysis → poll → result → cancel).

• Resume-safe batches — already-valid lesson files are skipped; interrupted runs continue where they stopped.

• CLI mode — edutube-mcp extract <url> works without any MCP client.

Related MCP server: YT-NINJA

Requirements

• Node.js ≥ 20

• A Google Gemini API key (GEMINI_API_KEY)

• Optional: YOUTUBE_API_KEY (metadata tool + faster playlist import)

• Optional but recommended: yt-dlp and ffmpeg on PATH (or 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"
      }
    }
  }
}

From source:

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 is clean JSON (progress goes to stderr), so it pipes straight into scripts and LMS importers.

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

• Configuration

• Tools

• Playlist lessons (Edutube pipeline)

• Model rotation

• CLI

• Long videos

• Changelog

Privacy & Limits

Media, URLs and prompts are sent to Google Gemini. Free-tier keys have small per-model daily quotas (~20 requests/day/model); automatic rotation spreads work across all models on your key. For production batches use a paid (pay-as-you-go) key. Private, age-restricted, DRM or region-blocked videos may fail. You are responsible for complying with YouTube and Gemini terms.

License

MIT — see 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.