Edutube MCP

🌐 Sitio del proyecto (GitHub Pages): https://engmohammeda.github.io/edutube-mcp/ — incluye un explorador en vivo de lecciones reales extraídas.

Convierte listas de reproducción y vídeos de YouTube en lecciones estructuradas, análisis, fotogramas y cuestionarios — con Google Gemini y rotación automática de modelos.

Servidor MCP stdio + CLI para agentes de IA y canalizaciones LMS. Pega una URL de lista de reproducción y obtén JSON por lección: diálogo textual con traducciones al árabe, expresiones clave, vocabulario, notas culturales/de pronunciación y un cuestionario de 10 preguntas — extraído del audio y de las imágenes reales, no solo de los subtítulos.

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

Características

• Importación de listas de reproducción por URL — pega cualquier URL de lista de reproducción de YouTube (o ID de lista, o URL de un solo vídeo). Las entradas se resuelven mediante la API de datos de YouTube cuando YOUTUBE_API_KEY está configurada; de lo contrario, automáticamente mediante yt-dlp --flat-playlist (sin necesidad de clave adicional).

• Extracción de lecciones estructuradas — esquema LMS integrado (dialogue / key_expressions / global_vocabulary / lesson_notes / quiz) con opción de esquema personalizado para tu propio formato.

• Canalización de vídeos largos con respaldo por ventanas — primero un pase de vídeo completo; si falla (cuota, plazos, VOD muy largos), cambia automáticamente a extracción por ventanas de 150 segundos con fusión y deduplicación.

• Rotación automática de modelos — cada modelo de Gemini tiene su propio grupo de cuota gratuita. Ante 429 RESOURCE_EXHAUSTED, la misma solicitud se reintenta de forma transparente en el siguiente modelo disponible. El catálogo de modelos se descubre en vivo desde la API de Gemini, por lo que los modelos nuevos (p. ej. gemini-3.6-flash, gemini-3.7-*) se unen a la rotación sin cambios de código.

• Herramientas de análisis multimodal — analyze_youtube_video (audio + imágenes), analyze_youtube_video_audio (prioridad al habla), extracción exacta de fotogramas JPEG con yt-dlp + ffmpeg, metadatos mediante la API de datos de YouTube.

• VOD largos y sesiones — analyze_long_youtube_video basado en tareas, seguimientos reutilizables con sessionId y trabajos en segundo plano de compatibilidad (start_long_youtube_analysis → poll → result → cancel).

• Lotes reanudables — los archivos de lección ya válidos se omiten; las ejecuciones interrumpidas continúan donde se detuvieron.

• Modo CLI — edutube-mcp extract <url> funciona sin ningún cliente MCP.

Related MCP server: YT-NINJA

Requisitos

• Node.js ≥ 20

• Una clave de API de Google Gemini (GEMINI_API_KEY)

• Opcional: YOUTUBE_API_KEY (herramienta de metadatos + importación de listas más rápida)

• Opcional pero recomendado: yt-dlp y ffmpeg en PATH (o YT_DLP_PATH)

Inicio rápido (cliente MCP)

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

Desde el código fuente:

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

Inicio rápido (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

La salida estándar es JSON limpio (el progreso va a stderr), por lo que se canaliza directamente a scripts e importadores LMS.

Herramientas (15)

Configuración

Integraciones de cliente

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 = "..." }

Documentación

• Instalación

• Configuración

• Herramientas

• Lecciones de listas de reproducción (canalización de Edutube)

• Rotación de modelos

• CLI

• Vídeos largos

• Registro de cambios

Privacidad y límites

Los medios, las URL y los prompts se envían a Google Gemini. Las claves del nivel gratuito tienen cuotas diarias pequeñas por modelo (~20 solicitudes/día/modelo); la rotación automática distribuye el trabajo entre todos los modelos de tu clave. Para lotes de producción, usa una clave de pago (pago por uso). Los vídeos privados, con restricción de edad, DRM o bloqueados por región pueden fallar. Eres responsable de cumplir los términos de YouTube y Gemini.

Licencia

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