YaleDevUni/yt-sub-mcp

MCP server for reading YouTube subtitles via the transcript panel endpoint

About yt-sub-mcp

YouTube 웹 UI의 "스크립트 표시" 패널이 쓰는 내부 엔드포인트(youtubei/v1/getpanel)를 사용합니다. 흔히 쓰이는 /api/timedtext 경로와 달리 레이트리밋에 걸리지 않고, 4시간짜리 영상도 요청 한 번에 전체 자막이 옵니다. 왜 이 경로를 쓰게 됐는지는 문제 해결 과정에 적어뒀습니다.

- 인증 불필요 — 쿠키도, API 키 발급도, 로그인도 없음 - 외부 바이너리 없음 — yt-dlp도 ffmpeg도 안 씁니다 - 영상당 요청 2회, 응답은 SQLite에 영속 캐싱

Claude Desktop이라면 claudedesktopconfig.json에:

사용 가능한 자막 언어 목록. 수동 제작인지 자동 생성인지 구분해서 보여줍니다.

getsubtitles(video, lang, timestamps, starttime, endtime, maxchars, refresh)

인자 기본값 설명 --------- video — URL 또는 11자 ID lang "en" 우선순위 순 콤마 구분 ("ko,en") timestamps false 블록마다 시작 시각 표시 starttime / endtime — 초 단위 구간 maxchars 20000 문자 예산 refresh false 캐시 우회

searchsubtitles(video, query, lang, context, maxhits)

특정 표현이 나오는 지점을 타임스탬프·딥링크와 함께 반환합니다. 전체를 읽는 것보다 훨씬 쌉니다.

video는 watch?v=, youtu.be, shorts, embed, live, 그리고 맨 ID를 모두 받습니다.

- 출력은 maxchars에서 잘리고 이어볼 타임스탬프를 함께 반환합니다. 그 값을 starttime으로 넣으면 이어집니다. - 평문은 ~90단어 문단, 타임스탬프 모드는 ~30초 구간으로 병합해 렌더링합니다. 큐마다 타임스탬프를 붙이면 토큰이 3배가 됩니다. - timestamps는 기본 꺼짐. 인용이나 링크가 필요할 때만 켜세요. - 권장 흐름: searchsubtitles로 위치를 찾고 → 그 구간만 getsubtitles로 읽기.

메모리 LRU(32) 앞단 + SQLite 영속 계층(500) 2단 구조입니다.

실측: 19분 영상 첫 요청 1,301ms → 이후 프로세스에서 0.7ms.

자막은 [text, start, duration] 삼중항 JSON을 zlib 압축해 저장합니다(427큐 25KB → 11KB, 43%).

환경변수 기본값 용도 --------- YTSUBMCPCACHE 1 0이면 디스크 계층 끔 YTSUBMCPCACHEDIR 아래 캐시 위치 YTSUBMCPCACHETTLDAYS 30 만료. 0이면 무기한

기본 경로는 macOS ~/Library/Caches/yt-sub-mcp/, 그 외 $XDGCACHEHOME/yt-sub-mcp/.

캐시는 기능을 죽이지 않습니다. 디스크가 차거나 DB를 열 수 없으면 로그만 남기고 메모리 전용으로 degrade합니다.

From the project README.

Maintaining this server?

Add the radar badge to your README — it shows your project was picked up by MCP Radar and links to this page:

[![On MCP Radar](https://mcp.liqiwa.com/badge.svg)](https://mcp.liqiwa.com/s/YaleDevUni--yt-sub-mcp.html)

Related MCP servers