Edutube MCP

🌐 项目站点（GitHub Pages）：https://engmohammeda.github.io/edutube-mcp/ — 包含真实提取课程的可视化浏览器。

将 YouTube 播放列表和视频转化为结构化课程、分析、帧和测验 — 借助 Google Gemini 和自动模型轮换。

MCP stdio 服务器 + CLI，适用于 AI 代理和 LMS 流水线。粘贴播放列表 URL，即可获得每课 JSON：逐字对话及阿拉伯语翻译、关键表达、词汇、文化/发音注释，以及 10 题测验 — 从实际音频和画面中提取，而不仅仅是字幕。

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

功能特性

• 通过 URL 导入播放列表 — 粘贴任意 YouTube 播放列表 URL（或播放列表 ID，或单个视频 URL）。当设置了 YOUTUBE_API_KEY 时，条目通过 YouTube Data API 解析，否则自动通过 yt-dlp --flat-playlist 解析（无需额外密钥）。

• 结构化课程提取 — 内置 LMS 模式（dialogue / key_expressions / global_vocabulary / lesson_notes / quiz），并提供自定义模式选项以适配你自己的格式。

• 长视频流水线与窗口回退 — 先进行全视频处理；如果失败（配额、截止时间、超长 VOD），则自动切换到 150 秒窗口提取，并进行合并与去重。

• 自动模型轮换 — 每个 Gemini 模型都有自己的免费层配额池。当遇到 429 RESOURCE_EXHAUSTED 时，同一请求会在下一个可用模型上透明重试。模型目录从 Gemini API 实时发现，因此新模型（例如 gemini-3.6-flash、gemini-3.7-*）无需修改代码即可加入轮换。

• 多模态分析工具 — analyze_youtube_video（音频 + 画面）、analyze_youtube_video_audio（语音优先）、通过 yt-dlp + ffmpeg 精确提取 JPEG 帧、通过 YouTube Data API 获取元数据。

• 长 VOD 与会话 — 基于任务的 analyze_long_youtube_video、可复用的 sessionId 后续追问，以及兼容性后台任务（start_long_youtube_analysis → 轮询 → 结果 → 取消）。

• 可安全恢复的批处理 — 已有效的课程文件会被跳过；中断的运行会从停止处继续。

• CLI 模式 — edutube-mcp extract <url> 无需任何 MCP 客户端即可使用。

Related MCP server: YT-NINJA

环境要求

• Node.js ≥ 20

• 一个 Google Gemini API 密钥（GEMINI_API_KEY）

• 可选：YOUTUBE_API_KEY（元数据工具 + 更快的播放列表导入）

• 可选但推荐：将 yt-dlp 和 ffmpeg 加入 PATH（或设置 YT_DLP_PATH）

快速开始（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"
      }
    }
  }
}

从源码构建：

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

快速开始（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

标准输出是干净的 JSON（进度信息输出到 stderr），因此可以直接管道传输到脚本和 LMS 导入器。

工具（15 个）

配置

客户端集成

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

文档

• 安装

• 配置

• 工具

• 播放列表课程（Edutube 流水线）

• 模型轮换

• CLI

• 长视频

• 更新日志

隐私与限制

媒体、URL 和提示词会发送到 Google Gemini。免费层密钥的每个模型每日配额较小（约 20 次请求/天/模型）；自动轮换会将工作分散到你密钥下的所有模型。对于生产环境批处理，请使用付费（按量付费）密钥。私密、年龄限制、DRM 或地区封锁的视频可能失败。你有责任遵守 YouTube 和 Gemini 的服务条款。

许可证

MIT — 参见 LICENSE。

阿拉伯语

Edutube MCP — 将 YouTube 播放列表和视频转化为可直接导入 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 的集成，请参阅上面的文档。