YouTube MCP Server

원본 claude-code-youtube-mcp 저장소를 기반으로 한 YouTube MCP 서버입니다. 이 버전은 STDIO와 Streamable HTTP 전송 방식을 모두 지원하므로, Claude Code용으로 로컬에서 실행하거나 Claude.ai 커스텀 커넥터용으로 원격 배포할 수 있습니다.

이 서버는 YouTube Data API v3 도구를 제공합니다: 동영상 검색, 메타데이터, 채널 정보, 재생목록, 댓글, 트렌딩 동영상, 참여도 분석, 자막, 챕터, SponsorBlock 정리, 가장 많이 다시 본 구간 히트맵 등이 포함됩니다.

원본 출처: https://github.com/wynandw87/claude-code-youtube-mcp

로컬 실행

npm install
npm run build
npm run start:http

엔드포인트:

GET  /health
POST /mcp

Related MCP server: YouTube MCP Server

환경 변수

YOUTUBE_API_KEY=your_key_here

API 키를 GitHub에 커밋하지 마세요. 로컬 환경, .env, 또는 배포 플랫폼의 환경 변수에 보관하세요.

Railway 배포

1. 이 GitHub 저장소를 Railway에 배포합니다.

2. Railway에 YOUTUBE_API_KEY 환경 변수를 추가합니다.

3. 시작 명령어를 다음과 같이 설정합니다:

npm run start:http

4. 공개 MCP 엔드포인트를 사용합니다:

https://your-domain/mcp

빠른 시작

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 상태로 표시되는지 확인하세요.

기능

자막 및 캡션

• 자막 가져오기 (get_transcript) - 타임스탬프가 포함된 전체 동영상 자막을 가져오며, 여러 언어를 지원합니다.

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

• 정리된 자막 (get_clean_transcript) - SponsorBlock을 통해 스폰서, 인트로, 아웃트로, 군더더기를 제거한 자막입니다.

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

검색 및 탐색

• 동영상 검색 (search_videos) - 날짜, 길이, 유형, 정렬 순서 필터를 지원하는 전체 YouTube 검색입니다.

• 채널 내 검색 (search_within_channel) - 특정 크리에이터의 동영상을 검색합니다.

• 트렌딩 동영상 가져오기 (get_trending_videos) - 지역 및 카테고리별 현재 트렌딩 동영상입니다.

• 채널 동영상 가져오기 (get_channel_videos) - 채널의 최근 업로드 동영상을 날짜 또는 조회수 기준으로 정렬하여 가져옵니다.

동영상 및 채널 정보

• 동영상 메타데이터 (get_video_metadata) - 제목, 설명, 길이, 조회수, 좋아요, 태그 등입니다.

• 채널 정보 (get_channel_info) - 구독자 수, 동영상 수, 설명, 국가입니다.

• 재생목록 항목 (get_playlist_items) - 재생목록의 모든 동영상을 위치 및 메타데이터와 함께 가져옵니다.

분석 및 참여도

• 참여도 계산 (calculate_engagement) - 공개 통계에서 좋아요율, 댓글율, 참여율을 계산합니다.

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

• 동영상 댓글 (get_video_comments) - 좋아요 수와 답글 수가 포함된 상위 댓글입니다.

유틸리티

• YouTube URL 파싱 (parse_youtube_url) - 모든 YouTube URL 형식에서 동영상/채널/재생목록 ID를 추출합니다.

사용법

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

또는 자연스럽게 질문하세요:

• "이 YouTube 동영상의 자막을 가져와서 요약해줘"

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

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

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

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

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

• "스폰서 읽는 부분 없이 정리된 자막을 가져와줘"

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

도구 참조

parse_youtube_url

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

매개변수:

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

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

get_transcript

YouTube 동영상의 전체 자막/캡션을 가져옵니다. API 키가 필요 없습니다.

매개변수:

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

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

search_transcript

동영상 자막 내에서 키워드나 구문을 검색합니다.

매개변수:

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

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

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

extract_chapters

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

매개변수:

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

get_clean_transcript

SponsorBlock을 통해 스폰서 읽는 부분, 인트로, 아웃트로, 군더더기를 제거한 자막을 가져옵니다.

매개변수:

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

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

get_most_replayed

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

매개변수:

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

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

search_videos

전체 필터를 지원하는 YouTube 검색입니다.

매개변수:

• query (문자열, 필수) - 검색어

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

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

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

• upload_date (문자열, 선택) - "hour", "day", "week", "month", "year"

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

get_video_metadata

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

매개변수:

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

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

get_channel_info

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

매개변수:

• url (문자열, 필수) - YouTube 채널 URL, @핸들 또는 채널 ID

반환값: 제목, 설명, 구독자/동영상/조회수, 국가, 커스텀 URL, 썸네일입니다.

get_playlist_items

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

매개변수:

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

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

get_channel_videos

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

매개변수:

• url (문자열, 필수) - YouTube 채널 URL, @핸들 또는 채널 ID

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

• order (문자열, 선택) - "date", "viewCount" (기본값: "date")

get_trending_videos

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

매개변수:

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

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

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

search_within_channel

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

매개변수:

• url (문자열, 필수) - YouTube 채널 URL, @핸들 또는 채널 ID

• query (문자열, 필수) - 검색어

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

get_video_comments

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

매개변수:

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

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

• order (문자열, 선택) - "relevance", "time" (기본값: "relevance")

calculate_engagement

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

매개변수:

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

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

작동 방식

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

참고: 5개의 도구는 API 키 없이 작동합니다 (트랜스크립트, 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단계의 명령을 사용하여 다시 설치하세요 (원래 설치했던 것과 동일한 범위를 사용하세요).

MCP 서버가 표시되지 않음

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

claude mcp list

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

서버가 시작되지 않음

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

2. YouTube Data API가 활성화되어 있는지 확인하세요:

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

   • "사용"이라고 표시되어야 합니다.

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

기여

풀 리퀘스트 환영합니다! 간단하고 초보자에게 친숙하게 유지해 주세요.

라이선스

MIT

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