youtube-transcript-mcp

Claude Code용 로컬 MCP 서버. 채팅에서 유튜브 URL을 주면 자동으로 트랜스크립트(+제목/채널/길이)를 가져온다. 자막이 있으면 자막을 쓰고, 없으면 로컬 mlx-whisper(Apple Silicon 네이티브 가속)로 STT를 돌린다.

필수 요구사항

• Apple Silicon Mac (M1 이상) 필수. server.py가 최상단에서 mlx_whisper를 무조건 import하기 때문에, 자막만 있는 영상을 쓸 계획이어도 Apple Silicon이 아니면 서버 자체가 기동되지 않는다. (Intel Mac / Linux / Windows는 지원하지 않음)

• Python 3.10 이상

• Claude Code CLI가 설치되어 있어야 함

Related MCP server: YouTube Video Summarizer MCP Server

사전 준비

brew install ffmpeg   # yt-dlp가 오디오 추출에 사용

설치

git clone https://github.com/thisisgonnabegreat/youtube-transcript-mcp.git
cd youtube-transcript-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

mcp 패키지는 2.0.0부터 FastMCP(mcp.server.fastmcp) API가 MCPServer로 대체되며 제거됐다. 이 프로젝트는 아직 FastMCP 기반이라 requirements.txt에서 mcp>=1.2.0,<2.0.0으로 버전을 고정해뒀다. 상한 없이 설치하면(mcp>=1.2.0만 지정) ModuleNotFoundError: No module named 'mcp.server.fastmcp'로 서버가 조용히 죽고, claude mcp add 시 30초 타임아웃으로만 나타나니 주의.

Claude Code에 등록

claude mcp add youtube-transcript -- $(pwd)/.venv/bin/python $(pwd)/server.py

등록 후 Claude Code 채팅에서 유튜브 링크를 주고 "이 영상 요약해줘" 같은 요청을 하면 자동으로 get_youtube_transcript 도구가 호출된다.

사용 예시

채팅에 아래처럼 입력하면:

https://www.youtube.com/watch?v=xxxxxxxxxxx
여기 중요한 내용 추출해줘

Claude가 자동으로 get_youtube_transcript(url="https://www.youtube.com/watch?v=xxxxxxxxxxx")를 호출하고, 아래와 같은 JSON을 받아 답변에 활용한다 (실제 반환 예시를 축약):

{
  "title": "영상 제목",
  "channel": "채널명",
  "duration": 297,
  "source": "subtitle",
  "language": "ko",
  "segments": [
    {"start": 0.0, "end": 1.47, "text": "첫 문장..."},
    {"start": 1.47, "end": 2.53, "text": "다음 문장..."}
  ],
  "full_text": "전체 텍스트를 이어붙인 문자열..."
}

파라미터

캐시가 있는 영상은 파라미터 없이 재요청해도 즉시 캐시(~/.cache/yt-transcript-mcp/{video_id}.json)에서 반환된다. 캐시를 무시하고 다시 받고 싶으면 force_stt=true로 호출하거나 해당 캐시 파일을 직접 지우면 된다.

동작 방식

1. URL에서 video_id 추출

2. 캐시(~/.cache/yt-transcript-mcp/{video_id}.json)에 있으면 즉시 반환

3. yt-dlp로 메타데이터 + 원본 언어 자막 존재 여부 확인

4. 자막 있으면 다운로드해서 타임스탬프 포함 세그먼트로 파싱

5. 자막 없으면 오디오만 내려받아 mlx-whisper(large-v3-turbo)로 STT

   • 60분 초과 영상은 자동 진행하지 않고 경고만 반환 (confirm_long=true로 재호출 시 진행)

   • 최초 STT 실행 시 Hugging Face에서 mlx-community/whisper-large-v3-turbo 모델(약 1.5GB)을 자동으로 내려받는다. 시간이 좀 걸리므로 "멈춘 것처럼" 보여도 기다리면 된다 (이후 실행부터는 로컬 캐시된 모델을 재사용해 빠름)

6. 결과를 캐시에 저장 후 반환

반환 형식

{
  "title": "...",
  "channel": "...",
  "duration": 754,
  "source": "subtitle | stt",
  "language": "ko",
  "segments": [{"start": 0.0, "end": 3.2, "text": "..."}],
  "full_text": "..."
}

알려진 제약 (스펙 기준 범위 밖)

• 재생목록 URL은 지원하지 않음 (개별 영상 URL만)

• 라이브 방송/프리미어는 지원하지 않음

• Apple Silicon 전용 (맨 위 필수 요구사항 참고)

보안 참고사항

• stdio 전용, 네트워크 포트 없음: Claude Code가 로컬 프로세스로 직접 실행하는 방식이라 외부에서 접근 가능한 포트를 열지 않는다.

• 인증/API 키 불필요: 이 서버 자체는 어떤 비밀키도 요구하거나 저장하지 않는다. (yt-dlp가 유튜브 공개 API/페이지에 접근하는 것뿐)

• URL을 검증 없이 그대로 요청: get_youtube_transcript는 받은 URL을 그대로 yt-dlp/requests에 넘겨 외부로 요청을 보낸다. 즉 이 도구가 처리하는 URL은 신뢰 경계(trust boundary) 바깥에서 왔다고 가정하고 다뤄야 한다 — 채팅 중 다른 텍스트(예: 웹페이지 요약, 이메일 등)에 섞여 들어온 URL을 확인 없이 그대로 이 도구에 전달하지 않는 걸 권장한다(프롬프트 인젝션으로 임의 URL을 요청하게 만드는 경로 차단).

• 캐시는 로컬 평문 저장: 결과가 ~/.cache/yt-transcript-mcp/{video_id}.json에 평문 JSON으로 남는다. 민감한 내용의 비공개 영상을 처리했다면 이 디렉터리를 수동으로 정리해야 한다.

• 의존성 버전 고정: mcp 패키지는 API 호환성 때문에 <2.0.0으로 고정했다(supply-chain 관점에서도 상한 없는 의존성보다 안전). yt-dlp, mlx-whisper, requests는 하한만 지정되어 있으니 정기적으로 pip list --outdated로 알려진 취약점 유무를 확인하는 걸 권장한다.

• 비밀정보 없음 확인됨: 전체 git 히스토리에 API 키/토큰/개인 절대경로 등은 포함되어 있지 않다 (.gitignore가 .venv, 캐시, 오디오 파일을 제외).

문제 해결

claude mcp list에서 Failed to connect — connection timed out가 뜨는 경우

서버 프로세스가 import 단계에서 조용히 죽었을 가능성이 크다. stdio 서버는 정상 기동해도 클라이언트가 붙기 전까지 아무 출력이 없어서, import 에러든 정상 대기든 겉보기엔 똑같이 "응답 없음"으로 보인다. 직접 import를 확인해서 원인을 좁힌다:

.venv/bin/python -c "from mcp.server.fastmcp import FastMCP; import yt_dlp, mlx_whisper, requests; print('OK')"

여기서 에러가 나면 그게 진짜 원인이다 (대표적으로 위에서 설명한 mcp 2.0.0 호환성 문제). OK가 뜨는데도 여전히 타임아웃이면 claude mcp remove youtube-transcript 후 claude mcp add로 재등록해본다.

오디오 다운로드/추출이 실패하는 경우

ffmpeg가 설치돼 있는지 확인 (brew install ffmpeg). yt-dlp가 오디오를 wav로 변환할 때 필요하다.

영상 정보를 못 가져온다는 에러

비공개/삭제/연령제한 영상일 수 있다. 에러 메시지에 원인이 그대로 담겨 반환된다.

라이선스

MIT

테스트 체크리스트 (완료 기준)

• claude mcp add로 정상 등록

• 자막 있는 한국어 영상 1개 테스트

• 같은 영상 재요청 시 캐시로 즉시 반환되는지 확인 (파일 mtime/해시로 검증됨)

• 자막 없는 영상(STT 경로) 1개 테스트 — 아직 미검증

• 60분 초과 영상에서 confirm_long 로직 확인 — 아직 미검증