YouTube MCP Server

Claude Code에 YouTube를 제공하는 MCP 서버 — 동영상 트랜스크립트, 검색, 메타데이터, 채널 정보, 재생목록, 댓글, 트렌딩 동영상, 참여도 분석, 챕터 추출, SponsorBlock 연동, 최다 재생 히트맵을 지원합니다. YouTube Data API v3, youtube-transcript, SponsorBlock을 사용합니다.

빠른 시작

1단계: API 키 받기

1. Google Cloud Console로 이동

2. 프로젝트 생성(또는 기존 프로젝트 선택)

3. YouTube Data API v3 활성화:

   • API 라이브러리로 이동

   • 사용 클릭

4. API 키 생성:

   • 사용자 인증 정보로 이동

   • 사용자 인증 정보 만들기 > API 키 클릭

5. 키 복사(3단계에서 필요)

2단계: 사전 요구 사항 설치

• Node.js 18+ - 여기에서 다운로드

• Claude Code CLI - 설치 가이드

3단계: MCP 서버 설치

3.1 저장소 클론

git clone https://github.com/wynandw87/claude-code-youtube-mcp.git
cd claude-code-youtube-mcp

3.2 의존성 설치

macOS / Linux / Windows:

npm install

참고: 의존성 설치와 서버 빌드가 한 단계에서 자동으로 수행됩니다.

3.3 Claude Code에 등록

설치 범위를 선택하세요:

YOUR_API_KEY를 실제 YouTube Data API 키로 바꾸고, dist/index.js의 전체 경로를 사용하세요.

팁: 전체 경로를 얻으려면 클론한 디렉토리에서 다음을 실행하세요:

• macOS/Linux: echo "$(pwd)/dist/index.js"

• Windows: echo %cd%\dist\index.js

macOS / Linux:

claude mcp add -s user youtube -e YOUTUBE_API_KEY=YOUR_API_KEY -- node /full/path/to/dist/index.js

Windows (CMD):

claude mcp add -s user youtube -e "YOUTUBE_API_KEY=YOUR_API_KEY" -- node "C:\full\path\to\dist\index.js"

Windows (PowerShell):

claude mcp add -s user youtube -e "YOUTUBE_API_KEY=YOUR_API_KEY" '--' node "C:\full\path\to\dist\index.js"

대안: npm 헬퍼 사용 (API 키가 환경 변수에 설정된 경우)

export YOUTUBE_API_KEY=YOUR_API_KEY
npm run install:claude

4단계: Claude Code 다시 시작

변경 사항을 적용하려면 Claude Code를 닫고 다시 엽니다.

5단계: 설치 확인

claude mcp list

youtube가 Connected 상태로 표시되어야 합니다.

Related MCP server: youtube-research

기능

트랜스크립트 및 캡션

• Get Transcript (get_transcript) - 타임스탬프가 포함된 전체 동영상 트랜스크립트를 가져오며, 여러 언어를 지원합니다

• Search Transcript (search_transcript) - 키워드나 구문이 동영상에서 나타나는 위치를 타임스탬프와 함께 찾습니다

• Clean Transcript (get_clean_transcript) - SponsorBlock을 통해 스폰서, 인트로, 아웃트로, 군더더기가 제거된 트랜스크립트

• Extract Chapters (extract_chapters) - 동영상 설명에서 챕터 타임스탬프를 파싱합니다

검색 및 탐색

• Search Videos (search_videos) - 날짜, 길이, 유형, 정렬 순서 필터를 지원하는 전체 YouTube 검색

• Search Within Channel (search_within_channel) - 특정 크리에이터의 동영상을 검색합니다

• Get Trending Videos (get_trending_videos) - 지역 및 카테고리별 현재 트렌딩 동영상

• Get Channel Videos (get_channel_videos) - 날짜 또는 조회수로 정렬된 채널의 최근 업로드

동영상 및 채널 정보

• Video Metadata (get_video_metadata) - 제목, 설명, 재생 시간, 조회수, 좋아요, 태그 등

• Channel Info (get_channel_info) - 구독자 수, 동영상 수, 설명, 국가

• Playlist Items (get_playlist_items) - 재생목록의 모든 동영상을 위치 및 메타데이터와 함께 제공

분석 및 참여도

• Calculate Engagement (calculate_engagement) - 공개 통계에서 좋아요율, 댓글율, 참여율 계산

• Most Replayed (get_most_replayed) - 시청자들이 가장 많이 다시 보는 구간을 보여주는 히트맵 데이터

• Video Comments (get_video_comments) - 좋아요 수와 답글 수가 포함된 주요 댓글

유틸리티

• Parse YouTube URL (parse_youtube_url) - 모든 YouTube URL 형식에서 동영상/채널/재생목록 ID 추출

사용 방법

설치 후 트리거 문구를 사용하여 YouTube 도구를 호출할 수 있습니다:

또는 자연스럽게 물어보세요:

• "이 YouTube 동영상의 트랜스크립트를 가져와서 요약해 줘"

• "이 동영상에서 가장 많이 다시 보는 구간은 어디야?"

• "이 채널에서 TypeScript에 관한 최근 동영상을 찾아줘"

• "이 동영상의 조회수와 좋아요 수는 얼마야?"

• "이 동영상의 댓글을 가져와서 감정을 요약해 줘"

• "이 튜토리얼의 챕터를 보여 줘"

• "스폰서 멘트 없이 깔끔한 트랜스크립트를 가져와 줘"

• "지금 게임 분야에서 YouTube 트렌딩은 뭐야?"

도구 참조

parse_youtube_url

모든 YouTube URL 형식을 파싱하여 식별자를 추출합니다. API 키가 필요 없습니다.

매개변수:

• url (string, 필수) - 모든 YouTube URL 또는 동영상 ID

지원 형식: youtube.com/watch?v=, youtu.be/, /shorts/, /embed/, /playlist?list=, /channel/, /@handle, /c/, /user/, 동영상 ID 단독

get_transcript

YouTube 동영상의 전체 트랜스크립트/캡션을 가져옵니다. API 키가 필요 없습니다.

매개변수:

• url (string, 필수) - YouTube 동영상 URL 또는 동영상 ID

• lang (string, 선택) - 캡션 언어 코드 (기본값: "en")

search_transcript

동영상 트랜스크립트에서 키워드 또는 구문을 검색합니다.

매개변수:

• url (string, 필수) - YouTube 동영상 URL 또는 동영상 ID

• query (string, 필수) - 검색할 키워드 또는 구문

• lang (string, 선택) - 캡션 언어 코드 (기본값: "en")

extract_chapters

동영상 설명에서 챕터 타임스탬프를 추출합니다.

매개변수:

• url (string, 필수) - YouTube 동영상 URL 또는 동영상 ID

get_clean_transcript

SponsorBlock을 통해 스폰서 멘트, 인트로, 아웃트로, 군더더기가 제거된 트랜스크립트를 가져옵니다.

매개변수:

• url (string, 필수) - YouTube 동영상 URL 또는 동영상 ID

• lang (string, 선택) - 캡션 언어 코드 (기본값: "en")

get_most_replayed

시청자들이 가장 많이 다시 보는 구간을 보여주는 "최다 재생" 히트맵 데이터를 가져옵니다.

매개변수:

• url (string, 필수) - YouTube 동영상 URL 또는 동영상 ID

참고: 히트맵 데이터를 사용하려면 조회수가 약 5만 회 이상이어야 합니다.

search_videos

완전한 필터 지원으로 YouTube를 검색합니다.

매개변수:

• query (string, 필수) - 검색어

• max_results (number, 선택) - 결과 수, 1-50 (기본값: 10)

• order (string, 선택) - "relevance", "date", "viewCount", "rating" (기본값: "relevance")

• duration (string, 선택) - "short" (4분 미만), "medium" (4-20분), "long" (20분 초과)

• upload_date (string, 선택) - "hour", "day", "week", "month", "year"

• type (string, 선택) - "video", "channel", "playlist" (기본값: "video")

get_video_metadata

YouTube 동영상의 상세 메타데이터를 가져옵니다.

매개변수:

• url (string, 필수) - YouTube 동영상 URL 또는 동영상 ID

반환값: 제목, 설명, 채널, 재생 시간, 조회/좋아요/댓글 수, 태그, 카테고리, 썸네일, 라이브 상태 등.

get_channel_info

YouTube 채널 정보를 가져옵니다.

매개변수:

• url (string, 필수) - YouTube 채널 URL, @handle 또는 채널 ID

반환값: 제목, 설명, 구독자/동영상/조회 수, 국가, 맞춤 URL, 썸네일.

get_playlist_items

YouTube 재생목록의 모든 동영상을 가져옵니다.

매개변수:

• url (string, 필수) - YouTube 재생목록 URL 또는 재생목록 ID

• max_results (number, 선택) - 항목 수, 1-50 (기본값: 25)

get_channel_videos

YouTube 채널의 최근 동영상을 가져옵니다.

매개변수:

• url (string, 필수) - YouTube 채널 URL, @handle 또는 채널 ID

• max_results (number, 선택) - 동영상 수, 1-50 (기본값: 25)

• order (string, 선택) - "date", "viewCount" (기본값: "date")

get_trending_videos

현재 트렌딩/인기 YouTube 동영상을 가져옵니다.

매개변수:

• region_code (string, 선택) - ISO 3166-1 alpha-2 국가 코드 (기본값: "US")

• category_id (string, 선택) - YouTube 카테고리 ID (예: "10" 음악, "20" 게임, "28" 과학/기술)

• max_results (number, 선택) - 결과 수, 1-50 (기본값: 10)

search_within_channel

특정 YouTube 채널 내에서 동영상을 검색합니다.

매개변수:

• url (string, 필수) - YouTube 채널 URL, @handle 또는 채널 ID

• query (string, 필수) - 검색어

• max_results (number, 선택) - 결과 수, 1-50 (기본값: 10)

get_video_comments

YouTube 동영상의 최상위 댓글을 가져옵니다.

매개변수:

• url (string, 필수) - YouTube 동영상 URL 또는 동영상 ID

• max_results (number, 선택) - 댓글 수, 1-100 (기본값: 20)

• order (string, 선택) - "relevance", "time" (기본값: "relevance")

calculate_engagement

YouTube 동영상의 참여도 지표를 계산합니다.

매개변수:

• url (string, 필수) - YouTube 동영상 URL 또는 동영상 ID

반환값: 조회 수, 좋아요 수, 댓글 수, 좋아요율, 댓글율, 전체 참여율.

작동 방식

이 MCP 서버는 stdio 전송을 통해 Claude Code에 연결되며 15개의 도구를 제공합니다:

참고: API 키 없이 작동하는 도구는 5개입니다(트랜스크립트, SponsorBlock, 히트맵, URL 파싱). 나머지 10개는 YouTube Data API v3 키가 필요합니다.

설정

환경 변수

YouTube API 할당량

YouTube Data API v3의 일일 할당량은 10,000유닛입니다. 도구마다 사용량이 다릅니다:

팁: 검색 작업은 비용이 가장 많이 듭니다. 최근 업로드만 필요하다면 search_within_channel(100유닛) 대신 get_channel_videos(1유닛)를 사용하세요.

문제 해결

API 키 수정

API 키를 잘못 입력했다면 제거하고 다시 설치하세요:

claude mcp remove youtube

그런 다음 위 3.3단계의 명령을 사용하여 다시 설치하세요(원래 설치했을 때와 동일한 범위(scope)를 사용하세요).

MCP 서버가 표시되지 않는 경우

서버가 설치되어 있는지 확인하세요:

claude mcp list

목록에 없으면 3단계에 따라 설치하세요.

서버가 시작되지 않는 경우

1. Google Cloud Console에서 API 키가 유효한지 확인하세요

2. YouTube Data API가 사용 설정되어 있는지 확인하세요:

   • API 라이브러리로 이동하세요

   • 'Enabled'라고 표시되어야 합니다

3. Node.js 버전을 확인하세요(18 이상 필요):

   node --version

4. 서버가 빌드되었는지 확인하세요 — dist/index.js가 없다면 npm install을 다시 실행하세요

연결 오류

1. dist/index.js가 존재하는지 확인하세요 — 없다면 npm install을 실행하세요

2. claude mcp add 명령에서 경로가 절대 경로인지 확인하세요

3. 구성 변경 후에는 Claude Code를 다시 시작하세요

할당량 초과

'quotaExceeded' 오류가 표시되면:

• 태평양 시간 기준 자정까지 기다리세요(할당량은 매일 초기화됩니다)

• 다른 API 키를 사용하세요

• 검색 도구(100유닛)보다 저비용 도구(get_video_metadata, 1유닛)를 우선 사용하세요

트랜스크립트를 사용할 수 없는 경우

일부 동영상은 트랜스크립트가 비활성화되어 있습니다. get_transcript 도구는 명확한 오류 메시지를 반환합니다. 다음을 시도해 보세요:

• 다른 언어 코드(예: lang: "es")

• 수동 자막이 없는 경우에도 자동 생성 자막을 사용할 수 있습니다

타임아웃 오류

연결이 느린 경우 YOUTUBE_TIMEOUT 환경 변수를 늘리세요:

claude mcp add -s user youtube -e YOUTUBE_API_KEY=YOUR_KEY -e YOUTUBE_TIMEOUT=60000 -- node /path/to/dist/index.js

현재 구성 보기

claude mcp list

기여

Pull Request는 언제나 환영합니다! 간단하고 초보자에게 친숙하게 유지해 주세요.

라이선스

MIT

Claude Code 커뮤니티를 위해 제작되었습니다