Skip to main content
Glama

youtube-mcp

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

youtube-mcp MCP server

GitHub Sponsors Ko-fi

소개

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

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합니다. 완료입니다.

Related MCP server: yt-fetch

설치

# 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 엔드포인트로 지정하세요.

구성

CLI 플래그

환경 변수

기본값

참고

--client-secret-file

YOUTUBE_CLIENT_SECRET_FILE

(없음)

Google OAuth JSON 경로

--client-id

YOUTUBE_CLIENT_ID

(없음)

비밀 파일 대신 사용

--client-secret

YOUTUBE_CLIENT_SECRET

(없음)

비밀 파일 대신 사용

--token-file

YOUTUBE_TOKEN_FILE

~/.config/youtube-mcp/token.json

리프레시 토큰 저장소

--host

MCP_HOST

0.0.0.0

바인드 호스트 (HTTP 모드 전용)

--port

MCP_PORT

9120

바인드 포트 (HTTP 모드 전용)

--stdio

MCP_TRANSPORT=stdio

(설정 안 됨)

HTTP 대신 stdio를 통해 MCP 통신. stdio 우선 MCP 클라이언트(Claude Desktop, mcp-inspector)가 서브프로세스로 실행할 때 사용.

--comfyui-url

COMFYUI_URL

(설정 안 됨, 브릿지 비활성화)

브릿지 도구용 ComfyUI HTTP URL

(플래그 없음)

COMFYUI_DEFAULT_CKPT

sd_xl_base_1.0.safetensors

브릿지 도구용 기본 체크포인트

전송 방식

서버는 기본적으로 Streamable HTTP를 사용합니다(Claude Code, MetaMCP, 원시 fetch에 적합). --stdio를 전달하거나 MCP_TRANSPORT=stdio를 설정하여 stdio 모드로 전환할 수 있습니다. 이는 Claude Desktop 및 MCP Inspector와 같은 stdio 우선 클라이언트가 기대하는 방식입니다:

// claude_desktop_config.json
{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "@miller-joe/youtube-mcp", "--stdio"],
      "env": {
        "YOUTUBE_CLIENT_SECRET_FILE": "/path/to/client_secret.json",
        "YOUTUBE_TOKEN_FILE": "/path/to/token.json"
      }
    }
  }
}

Stdio 모드는 OAuth 토큰 사전 확인을 건너뜁니다. 서버는 저장된 토큰 없이도 부팅되며 도구 호출 시점에 인증 오류를 발생시킵니다. Claude Desktop을 연결하기 전에 HTTP 모드에서 youtube-mcp --auth --client-secret-file <path>를 한 번 실행하여 리프레시 토큰을 생성하세요.

도구

동영상

  • 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+가 필요합니다.

로드맵

구현 완료:

  • 동영상: 목록, 조회, 메타데이터 업데이트, 제목 일치 확인을 통한 삭제.

  • 자막: 업로드, 목록, 삭제.

  • 쇼츠: list_my_shorts(길이 필터) 및 get_shorts_analytics(creatorContentType==SHORTS).

  • 재생목록: 생성, 추가.

  • 댓글: 목록, 답글, 관리.

  • 분석: 채널 분석 쿼리.

  • ComfyUI 썸네일 브릿지: generate_and_set_thumbnail.

계획 중:

  • 재개 가능한 업로드를 지원하는 동영상 업로드(video_upload).

  • 대량 기록 데이터 내보내기를 위한 보고 API.

라이선스

MIT © Joe Miller

지원

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

GitHub Sponsors Ko-fi

Available Tools

15 tools
add_to_playlistB

Add a video to an existing playlist. Both playlist_id and video_id are YouTube IDs (not URLs).

Inputs: playlist_id (required), video_id (required).

create_playlistB

Create a new playlist on the authenticated channel. Default privacy is 'private'.

Inputs: title (required), description, privacy_status.

delete_captionA

Delete a caption track by ID. Use list_captions to find the track ID first.

Inputs: caption_id (required).

delete_videoA

Permanently delete a video. Requires confirm_video_title to match the video's current title exactly — guards against deleting the wrong video by ID. Deletion is irreversible.

Inputs: video_id (required), confirm_video_title (required).

get_shorts_analyticsA

Query YouTube Analytics restricted to Shorts for the authenticated channel. Applies filters=creatorContentType==SHORTS on top of the usual start_date/end_date/metrics/dimensions knobs.

Inputs: start_date (required), end_date (required), metrics, dimensions, +2 more.

get_videoA

Fetch full details for one video by ID — snippet, status, statistics, duration.

Inputs: video_id (required).

list_captionsA

List caption tracks on a video with their language, name, status, and whether they are drafts.

Inputs: video_id (required).

list_commentsB

List top-level comment threads on a video (newest first). Returns comment IDs, authors, text, and like counts.

Inputs: video_id (required), max_results.

list_my_shortsA

List your recent Shorts — scans the most recent uploads and filters to videos ≤60s. Useful when the Data API doesn't expose a direct Shorts filter.

Inputs: max_candidates.

list_my_videosA

List videos on the authenticated channel (newest first via the uploads playlist). Returns video IDs, titles, view counts, and privacy status.

Inputs: max_results, page_token.

moderate_commentA

Change the moderation status of a comment: heldForReview (hide pending approval), published (approve), or rejected (delete).

Inputs: comment_id (required), moderation_status (required).

query_channel_analyticsA

Query YouTube Analytics for the authenticated channel. Returns tabular data — useful for views/watch-time/retention/traffic-source reports. Date-ranged and optionally grouped by dimensions.

Inputs: start_date (required), end_date (required), metrics, dimensions, +3 more.

reply_to_commentB

Reply to a top-level comment. Requires youtube.force-ssl scope.

Inputs: parent_id (required), text (required).

update_video_metadataA

Update a video's metadata — title, description, tags, category, or privacy. Only provide fields you want changed.

Inputs: video_id (required), title, description, tags, +2 more.

upload_captionA

Upload a caption track (SRT or WebVTT) to a video. Creates a new track — use a distinct name per language/track, or is_draft=true while iterating.

Inputs: video_id (required), language (required), caption_text (required), name, +2 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 15 tools

    Disambiguation5/5

    Each tool targets a distinct resource and action. Analytics tools are clearly differentiated (general vs Shorts-specific), and video list vs Shorts list is scoped by content type. Comments, captions, and playlists each have their own dedicated tools with no overlap.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun snake_case pattern (list_, get_, create_, update_, delete_, upload_, reply_to_, add_to_, moderate_, query_). There are no mixed conventions or cryptic abbreviations, making the naming predictable and easy to reason about.

    Tool Count5/5

    15 tools cover a broad YouTube management surface without feeling bloated. The set is well-scoped for the server's purpose—video, playlist, caption, comment, and analytics operations—and each tool has a clear role within that scope.

    Completeness3/5

    The coverage has significant gaps, especially for playlists: there is no way to list, retrieve, delete, or remove items from playlists, creating dead ends after creation. Caption updates are also absent (only create and delete), although video CRUD and comment moderation are well covered.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers