youtube-transcript-mcp

코딩 에이전트가 YouTube 동영상 트랜스크립트를 읽고 검색할 수 있게 해주는 MCP 서버입니다. API 키도, Google 계정도, 가입할 것도 필요 없습니다. YouTube의 공개 엔드포인트를 통해 자막을 가져오고, 원시 트랜스크립트 덤프가 제공하지 않는 한 가지 작은 기능, 즉 챕터 요약을 추가합니다.

이 프로젝트는 제가 개인적으로 쓰려고 만든 작은 도구에서 시작했습니다. YouTube 링크가 포함된 대화를 자주 접하게 되었고, 그 동영상이 실제로 무엇을 말하는지 알아야 했는데, 트랜스크립트를 계속 복사해서 붙여넣는 것이 시간 낭비였습니다. 그래서 Model Context Protocol에서 실행되는 모든 것이 그냥 물어볼 수 있는 재사용 가능한 서버가 되었습니다.

기능

네 가지 도구가 있습니다.

• get_transcript(video_url_or_id, languages=["en"], include_timestamps=False)는 전체 트랜스크립트를 일반 텍스트로 가져옵니다. 전체 YouTube URL(watch?v=, youtu.be, /embed/, /shorts/, /live/) 또는 11자리 동영상 ID만 받습니다.

• get_video_metadata(video_url_or_id)는 YouTube의 인증 없는 oEmbed 엔드포인트를 통해 제목, 채널 이름, 채널 URL, 썸네일을 반환합니다. 업로드 날짜나 전체 설명은 의도적으로 반환하지 않습니다. 그 이유는 공식 Data API 키가 필요하고, 여기서 핵심은 키가 필요 없다는 것이기 때문입니다.

• search_transcript(video_url_or_id, query, languages=["en"])는 키워드나 문구와 일치하는 세그먼트를 대소문자 구분 없이 찾아내며, 각 세그먼트에 [mm:ss] 타임스탬프가 포함되어 모델이 동영상에서 해당 내용이 언급된 위치를 가리킬 수 있습니다.

• summarize_chapters(video_url_or_id, gap_seconds=4.0, min_chunk_seconds=45.0, languages=["en"])는 트랜스크립트를 자연스러운 멈춤 지점에서 대략적인 시간 블록 청크로 나누어 반환하므로, 에이전트가 거대한 덩어리를 통째로 삼키는 대신 섹션별로 요약할 수 있습니다. 이는 휴리스틱이며, YouTube의 실제 챕터 데이터가 아닙니다.

모든 도구는 오류를 포함한 일반 문자열을 반환합니다(예: "Error: captions are disabled for this video"). 호출하는 에이전트에게 예외가 표시되지 않으며, 스택 트레이스도 유출되지 않습니다.

Related MCP server: youtube-mcp

의도적으로 하지 않는 일

• 자막이 비활성화된 동영상, 비공개 또는 이용할 수 없는 동영상, 자막이 없는 라이브 스트림에서는 작동하지 않습니다. 추측하는 대신 그렇게 명시합니다.

• YouTube Data API에 의존하지 않습니다. 설계상, 키 없이 업로드 날짜나 전체 설명을 얻을 수 없습니다.

• 캐시하지 않습니다. 같은 동영상에 대한 두 번의 호출은 매번 다시 가져옵니다. 이 도구의 실제 사용에는 충분합니다. 대량으로 필요해지면 캐싱을 추가하세요.

설정

Python 3.11+ 및 uv가 필요합니다.

uv sync

독립 실행으로 시작을 확인합니다:

uv run server.py

MCP stdio 입력을 기다리며 대기하므로, 클라이언트가 연결될 때까지 아무것도 하지 않는 것처럼 보입니다. 정상입니다. Ctrl+C로 종료합니다.

MCP 클라이언트에 등록

클라이언트의 MCP 설정에 추가합니다. 서버는 stdio로 호출되므로 구성은 명령줄입니다. Claude CLI를 예시로 사용하면:

claude mcp add youtube-transcript -- uv --directory /absolute/path/to/youtube-transcript-mcp run server.py

또는 JSON 구성에서:

{
  "mcpServers": {
    "youtube-transcript": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/youtube-transcript-mcp", "run", "server.py"]
    }
  }
}

힘들게 얻은 교훈

• 자막(자동 생성 또는 수동)이 있는 동영상만 작동합니다. 자막이 없는 동영상은 명확한 오류를 반환하는데, 이는 의도적인 선택입니다. 빈 결과는 조용한 실패처럼 보이지만, 오류는 그 원인을 명확히 합니다.

• 언어 목록이 중요합니다. languages=["en"]은 영어 트랙이 존재할 때 영어 트랙을 가져옵니다. 채널이 다른 언어로만 업로드하는 경우 해당 언어 코드를 전달하세요.

• mcp>=1.28.1을 고정하되 2.0 미만으로 유지하세요. mcp 2.x는 mcp.server.fastmcp를 이름을 바꾸었고, 서버 시작 시 import가 조용히 실패합니다. 실제로 로드되는 버전을 사용하세요.

라이선스

MIT. LICENSE를 참조하세요.