Edutube MCP

🌐 프로젝트 사이트 (GitHub Pages): https://engmohammeda.github.io/edutube-mcp/ — 실제 추출된 강의의 라이브 탐색기를 포함합니다.

YouTube 재생 목록과 동영상을 구조화된 강의, 분석, 프레임 및 퀴즈로 변환 — Google Gemini와 자동 모델 로테이션 사용.

AI 에이전트 및 LMS 파이프라인을 위한 MCP stdio 서버 + CLI. 재생 목록 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 스키마(대화 / 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(메타데이터 도구 + 더 빠른 재생 목록 가져오기)

• 선택 사항이지만 권장: PATH에 yt-dlp 및 ffmpeg(또는 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초 창 대체 경로가 있는 긴 동영상 경로, 병합 및 중복 제거.

• 멀티모달 분석, 정확한 JPEG 프레임 추출, 메타데이터, 고정 타임아웃이 있는 클라이언트를 위한 백그라운드 기능을 포함한 15개의 MCP 도구.

빠른 시작: .env.example을 .env로 복사하고 GEMINI_API_KEY를 설정한 다음 npm install && npm run build && npm start를 실행하거나 CLI를 직접 사용하세요. 자세한 내용과 Claude Code, Cursor, Codex와의 통합은 위 문서를 참조하세요.