youtube-mcp

채널 소유자를 위한 OAuth 인증 YouTube MCP — 동영상 메타데이터 수정, 댓글 답글 및 관리, 재생목록 관리, 채널 분석 쿼리, 그리고 ComfyUI 브리지를 통한 AI 썸네일 생성 및 설정이 가능합니다. 이 분야의 주류인 읽기 전용 Data API v3 래퍼를 넘어선 기능을 제공합니다.

MCP Server Series의 일부입니다.

소개

대부분의 기존 YouTube MCP는 Data API v3를 사용하는 API 키를 통해 동영상 검색, 공개 메타데이터 가져오기 등 읽기 전용 작업만 수행합니다. 이 도구는 **OAuth 2.0 (Authorization Code + PKCE)**을 사용하여 채널에 직접 쓰기 작업이 가능합니다. 동영상 제목/설명/태그 업데이트, 댓글 답글, 스팸 관리, 재생목록 관리를 수행할 수 있습니다. 또한 채널 통계를 위한 별도의 YouTube Analytics API를 호출하며, 핵심 도구인 ComfyUI를 통한 썸네일 생성 및 YouTube 설정을 단일 MCP 호출로 처리합니다.

Claude, use generate_and_set_thumbnail on video abc123:
  prompt: "cyberpunk hacker at keyboard, neon blue and pink, high contrast"

→ ComfyUI가 1280×720으로 렌더링 → youtube-mcp가 바이트를 가져옴 → thumbnails.set으로 POST 전송. 완료.

설치

# npx — no install
npx @miller-joe/youtube-mcp --help

# Docker
docker run -p 9120:9120 \
  -e YOUTUBE_CLIENT_ID=... \
  -e YOUTUBE_CLIENT_SECRET=... \
  -e YOUTUBE_TOKEN_FILE=/token/token.json \
  -v $PWD/token:/token \
  ghcr.io/miller-joe/youtube-mcp:latest

설정 — Google Cloud 1회성 작업 (~10분)

1. Google 계정 + YouTube 채널 — 손실 위험이 있는 워크스페이스 계정이 아닌 개인 계정을 사용하세요.

2. Google Cloud 프로젝트 (https://console.cloud.google.com) — 원하는 이름으로 생성하세요 (예: youtube-mcp).

3. API 활성화:

   • YouTube Data API v3

   • YouTube Analytics API

4. OAuth 동의 화면 — 외부(External), 앱 이름, 지원 이메일을 설정하고, 범위(Scopes)에 다음을 추가하세요:

   • youtube.upload

   • youtube.force-ssl

   • yt-analytics.readonly

5. 테스트 모드를 유지하세요. 본인을 테스트 사용자로 추가하세요(필수). 프로젝트 소유자로서 리프레시 토큰은 만료되지 않습니다.

6. OAuth 클라이언트 ID 생성: 애플리케이션 유형 = 데스크톱 앱. JSON 파일을 다운로드하세요.

7. 대화형 인증 흐름 실행:

   npx @miller-joe/youtube-mcp --auth --client-secret-file ./client_secret.json

   브라우저가 열리면 → YouTube 채널과 연결된 Google 계정으로 로그인 → 요청된 범위를 승인하세요. 성공 시 리프레시 토큰이 ~/.config/youtube-mcp/token.json에 저장됩니다.

8. 서버 시작:

   npx @miller-joe/youtube-mcp --client-secret-file ./client_secret.json

   또는 환경 변수를 통해 클라이언트 자격 증명을 제공하세요: YOUTUBE_CLIENT_SECRET_FILE, 또는 YOUTUBE_CLIENT_ID + YOUTUBE_CLIENT_SECRET.

MCP 클라이언트 연결

claude mcp add --transport http youtube http://localhost:9120/mcp

또는 MCP 게이트웨이를 Streamable HTTP 엔드포인트로 지정하세요.

구성

도구

동영상

• list_my_videos — 인증된 채널의 업로드 동영상 목록(페이지네이션)

• get_video — 동영상 상세 정보

• update_video_metadata — 제목 / 설명 / 태그 / 카테고리 / 공개 범위

• delete_video — 동영상 영구 삭제. 잘못된 삭제를 방지하기 위해 현재 제목과 일치하는 confirm_video_title이 필요합니다.

자막

• list_captions — 동영상 자막 트랙 목록(언어, 이름, 상태, 초안 플래그)

• upload_caption — SRT 또는 WebVTT 자막 트랙 업로드

• delete_caption — 자막 트랙 삭제

쇼츠(Shorts)

• list_my_shorts — 최근 업로드된 쇼츠 찾기(60초 이하 길이로 필터링)

• get_shorts_analytics — 쇼츠로 제한된 YouTube 분석 쿼리 (creatorContentType==SHORTS)

재생목록

• create_playlist — 재생목록 생성(기본값 비공개)

• add_to_playlist — 기존 재생목록에 동영상 추가

댓글

• list_comments — 동영상의 최상위 댓글 스레드

• reply_to_comment — 최상위 댓글에 답글 작성

• moderate_comment — 댓글 보류 / 승인 / 거부

분석

• query_channel_analytics — 날짜 범위별 지표(선택적 차원 및 필터 포함)

브리지 (COMFYUI_URL 설정 시)

• generate_and_set_thumbnail — ComfyUI를 통해 썸네일을 생성하고 단일 호출로 동영상에 설정

할당량 참고

YouTube Data API 무료 티어 = 일일 10,000 유닛. 주요 작업 비용:

• videos.list, commentThreads.list — 각 1 유닛

• videos.update, comments.insert, thumbnails.set — 각 50 유닛

• videos.insert (업로드) — 1,600 유닛 → 무료 티어에서 일일 약 6회 업로드 가능

대부분의 크리에이터 운영 워크플로우는 무료 한도 내에서 충분히 가능합니다.

아키텍처

┌────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  MCP client    │────▶│  youtube-mcp     │────▶│  YouTube APIs   │
│  (Claude etc.) │◀────│  (this server)   │◀────│  (Data/Analytics)│
└────────────────┘     └────────┬─────────┘     └─────────────────┘
                                │
                                │ (bridge tools only)
                                ▼
                       ┌──────────────────┐
                       │  ComfyUI         │
                       │  (txt2img)       │
                       └──────────────────┘

OAuth 리프레시 토큰은 로컬에 캐시되며 만료 직전에 갱신됩니다. 브리지 도구는 내부적으로 ComfyUI에서 이미지 바이트를 다운로드하므로 ComfyUI가 공개적으로 접근 가능할 필요는 없습니다.

개발

git clone https://github.com/miller-joe/youtube-mcp
cd youtube-mcp
npm install
npm run dev
npm run build
npm test

Node 20+가 필요합니다.

로드맵

• [x] 동영상 목록 / 가져오기 / 메타데이터 업데이트

• [x] 재생목록 생성 + 추가

• [x] 댓글 목록 / 답글 / 관리

• [x] 채널 분석 쿼리

• [x] ComfyUI 썸네일 브리지 (generate_and_set_thumbnail)

• [x] 자막 업로드 + 목록 + 삭제 (upload_caption, list_captions, delete_caption)

• [x] 제목 일치 확인을 통한 동영상 삭제

• [x] 쇼츠 편의 기능: list_my_shorts (길이 필터) + get_shorts_analytics (creatorContentType==SHORTS)

• [ ] 동영상 업로드 (video_upload) — 재개 가능한 업로드 지원

• [ ] 대량 과거 데이터 내보내기를 위한 보고 API

라이선스

MIT © Joe Miller

지원

이 도구가 시간을 절약해 주었다면 개발 후원을 고려해 주세요: