YouTube MCP Server

교육용 YouTube 동영상에서 자막과 시각적으로 의미 있는 프레임을 추출하여 Claude, ChatGPT 등 MCP 호환 클라이언트에서 사용할 수 있게 해주는 Python 기반 Model Context Protocol (MCP) 서버입니다.

기능 소개

AI 어시스턴트에게 YouTube URL을 주면 다음과 같은 작업을 수행할 수 있습니다:

1. 자막 읽기 — 타임스탬프가 포함된 전체 자막을 제공하여 요약, Q&A, 콘텐츠 분석에 활용할 수 있습니다.

2. 동영상 보기 — 5단계 컴퓨터 비전 파이프라인이 가장 정보가 풍부한 프레임을 추출하고, 품질을 점수화하며, 중복을 제거한 뒤 AI가 "볼 수 있는" base64 인코딩 JPEG로 반환합니다.

수동 다운로드가 필요 없습니다. 복사-붙여넣기도 필요 없습니다. URL을 붙여넣고 질문하기만 하면 됩니다.

도구(Tools)

get_transcript

youtube-transcript-api를 사용하여 동영상의 자막을 가져옵니다.

매개변수:

• url (필수) — YouTube 동영상 URL

• language (선택, 기본값: "en") — 선호하는 자막 언어

• prefer_manual (선택, 기본값: true) — 자동 생성 자막보다 수동 작성 자막을 우선

반환값: 깔끔하고 타임스탬프가 포함된 자막 블록:

[00:00:00] So I want to start by offering you a free ...
[00:00:15] The key insight here is that ...

get_video_frames

가장 의미 있는 시각적 순간을 표면화하기 위해 전체 동영상 분석 파이프라인을 실행합니다.

매개변수:

• url (필수) — YouTube 동영상 URL

• max_frames (선택, 기본값: 20) — 반환할 최대 프레임 수 (상한: 40)

• scene_threshold (선택, 기본값: 0.25) — FFmpeg 장면 전환 감지 민감도

• output_width (선택, 기본값: 640) — 반환되는 JPEG의 너비 (높이는 비례)

• min_importance_score (선택, 기본값: 0.35) — 최소 복합 품질 점수

반환값:

• 메타데이터: video_id, duration_seconds, pipeline_stats, fallback_used

• 프레임 블록: 각 블록에 timestamp_ms, composite_score, base64 인코딩 JPEG 이미지 포함

• 반환된 모든 프레임의 타임스탬프와 점수를 나열한 인덱스

프레임 파이프라인 (5단계)

빠른 시작

사전 요구 사항

• Python 3.11

• ffmpeg — 동영상 처리

• Tesseract OCR — 프레임 내 텍스트 감지

macOS:

brew install ffmpeg tesseract

Ubuntu / Linux:

sudo apt-get install ffmpeg tesseract-ocr tesseract-ocr-eng

Windows: ffmpeg와 Tesseract를 다운로드한 후 둘 다 PATH에 추가합니다.

확인:

ffmpeg -version
tesseract --version

설치

# Clone the repository
git clone https://github.com/Ayush-Mamgain/youtube-mcp-server.git
cd youtube-mcp-server

# Create a virtual environment
python3 -m venv venv
source venv/bin/activate        # macOS / Linux
# venv\Scripts\activate      # Windows

# Install dependencies
pip install -r requirements.txt

설정

프로젝트 루트에 .env 파일을 생성합니다:

LOG_LEVEL=DEBUG
MCP_HTTP_PORT=8000

선택적 튜닝 변수 (생략 시 config.py 기본값 사용):

서버 시작

python server.py

서버는 http://localhost:8000에서 시작됩니다.

Claude.ai에 연결하기 (로컬)

1. 서버 시작: python server.py

2. Claude.ai → 설정 → 통합 → MCP 서버 추가로 이동

3. 다음 입력: http://localhost:8000/mcp

클라우드 호스팅 Claude가 서버에 접근하려면 서버를 공개적으로 노출해야 합니다 (아래 배포 섹션 참조).

API 엔드포인트

프로젝트 구조

youtube-mcp-server/
├── server.py              # MCP entry point — FastMCP + Starlette HTTP server
├── config.py              # Loads and validates environment variables
├── logger.py              # stderr-only logging
├── url_parser.py          # Validates YouTube URLs and extracts video IDs
├── transcript.py          # Fetches captions via youtube-transcript-api
├── downloader.py          # Phase 1 — video download with yt-dlp
├── frame_extractor.py     # Phase 2 — scene-change frame extraction via ffmpeg
├── scorer.py              # Phase 3 — multi-signal frame scoring (OpenCV + Tesseract)
├── deduplicator.py        # Phase 4 — perceptual-hash deduplication
├── frame_loader.py        # Phase 5 — resize, JPEG encode, base64
├── video_frames.py        # Orchestrates Phases 1–5 with semaphore and cleanup
├── requirements.txt       # Pinned Python dependencies
└── .gitignore             # Excludes .env, venv, caches, test artifacts

개발 워크플로우

이 프로젝트는 9개의 독립적인 단계로 구축되었으며, 각 단계마다 자체 테스트 파일과 검증 절차가 있습니다:

핵심 원칙: 각 단계는 다음 단계로 진행하기 전에 검증됩니다. python test_stage{N}.py를 실행하여 검증하세요.

배포

Docker 지원은 계획되어 있지만 아직 구성되지 않았습니다. 컨테이너화가 완료되면 이 섹션이 업데이트됩니다.

현재로서는 Python 3.11, ffmpeg, Tesseract가 설치된 모든 머신에서 서버가 직접 실행됩니다. Docker가 준비되면 권장 호스팅 옵션:

• Railway

• Fly.io

• Render

배포 후 Claude.ai 통합 URL을 다음으로 업데이트하세요:

https://YOUR-DEPLOYMENT-URL/mcp

설계 노트

• 모든 로깅은 stderr로만 출력됩니다. stdout은 MCP 통신 전용으로 예약되어 있습니다.

• 스레드 안전: get_video_frames 파이프라인은 threading.Semaphore(1)을 사용하여 동시 다운로드로 인한 시스템 과부하를 방지합니다.

• 자동 정리: 동영상 처리 중 생성된 임시 파일은 각 실행 후 삭제됩니다.

• 엄격한 검증: 동영상 ID는 ^[A-Za-z0-9_-]{11}$ 패턴으로 검증됩니다. 재생 목록 전용 URL, 채널 URL, 잘못된 입력은 명확한 오류 메시지와 함께 거부됩니다.

• 우아한 대체(graceful degradation): 모든 프레임이 최소 중요도 임계값보다 낮은 점수를 받으면 파이프라인은 상위 5개 프레임으로 대체하고 fallback_used: true로 표시합니다.

라이선스

MIT © Ayush Mamgain

감사의 말

FastMCP, Starlette, yt-dlp, youtube-transcript-api, OpenCV로 구축되었습니다.