YouTube MCP 서버

Claude Desktop, Claude Code, Codex와 같은 MCP 클라이언트에서 YouTube를 사용하기 위한 오픈소스 Model Context Protocol(MCP) 서버입니다.

주요 워크플로는 다음과 같습니다:

1. MCP 클라이언트에 노래 목록을 제공합니다.

2. 아무것도 변경하기 전에 순위가 매겨진 YouTube 매치를 검토합니다.

3. 선택한 동영상으로 비공개 재생목록을 만듭니다.

이 서버는 또한 YouTube 검색과 동영상, 채널, 재생목록, 댓글 읽기를 위한 할당량을 고려한 도구를 제공합니다.

[!IMPORTANT] TypeScript 패키지, stdio 서버, 공개 및 인증된 읽기, PKCE OAuth, 음악 준비, 확인된 새 재생목록 생성, 전체 미리보기 재생목록 변경이 구현되어 테스트되었습니다. 준비된 음악 초안은 새 재생목록에 커밋하거나 소유한 기존 재생목록에 추가할 수 있습니다.

설계 목표

• 커밋 전 미리보기 의미론을 갖춘 안전한 재생목록 쓰기.

• 공식 YouTube Data API v3 엔드포인트만 사용.

• 자체 Google OAuth 클라이언트 사용; 이 프로젝트는 공유 Google 자격 증명을 제공하지 않습니다.

• 가능할 때마다 운영체제 키체인에 비밀 저장.

• 예측 가능한 할당량 사용, 페이지네이션, 캐싱, 재시도, 정규화된 오류.

• 간단한 설치와 작은 공격 표면을 위한 로컬 stdio 전송.

• YouTube 콘텐츠를 신뢰할 수 없는 데이터로 취급하는 구조화되고 제한된 도구 출력.

• Node.js 20.17 이상에서 크로스 플랫폼 TypeScript 지원.

Related MCP server: youtube-music-mcp

계획된 v1 범위

읽기 도구

• 동영상, 채널, 재생목록 검색.

• 동영상, 채널, 재생목록, 댓글 데이터 읽기.

• 인증된 사용자의 채널, 업로드, 재생목록 읽기.

• 명시적이고 상태 없는 페이지네이션을 위한 공급자 페이지 토큰 반환.

음악 재생목록 워크플로

• 준비 요청당 최대 50개의 구조화된 트랙 수락.

• 유력한 YouTube 뮤직비디오 매치 검색 및 순위 지정.

• 약한 매치를 조용히 선택하는 대신 모호성과 대안 표시.

• 명시적으로 선택된 매치를 새 재생목록 또는 소유한 기존 재생목록에 커밋.

• 새 재생목록을 기본적으로 private으로 설정.

댓글 관리

• 동영상에 최상위 댓글 게시 또는 기존 댓글에 답글.

• 미리보기와 일회용 핸들 뒤에서 댓글 삭제 또는 관리 상태 설정.

• 재생목록 쓰기에 이미 요청된 youtube.force-ssl 범위를 사용하므로 추가 동의가 필요 없습니다.

재생목록 관리

• 재생목록 생성 및 동영상 추가.

• 재생목록 메타데이터 또는 개인정보 업데이트.

• 재생목록 항목 재정렬 또는 제거.

• 단기 일회용 확인 핸들이 발급된 후 재생목록 삭제.

재생목록 업데이트, 항목 제거/재정렬, 삭제는 두 가지 도구를 사용합니다: youtube_prepare_playlist_mutation은 쓰기 없이 정확한 diff와 10분 핸들을 반환하고, youtube_apply_playlist_mutation은 해당 핸들을 한 번 소비하기 전에 소유권과 재생목록 스냅샷을 다시 확인합니다.

동영상 업로드 및 수명주기

• 재개 가능한 업로드를 통해 로컬 동영상 파일 업로드, 기본값은 private.

• 소유한 동영상의 제목, 설명, 태그 또는 개인정보 업데이트. 지정되지 않은 필드는 지워지지 않고 유지됩니다.

• 로컬 JPEG 또는 PNG에서 맞춤 썸네일 설정.

• 소유한 동영상 미리보기 후 영구 삭제.

동영상 쓰기에는 추가 youtube.upload 범위가 필요하며, 해당 범위 없이 프로필이 인증된 경우 완전히 거부합니다. youtube_plan_video_upload는 YouTube에 연락하지 않고 파일을 검증하고 비용을 보고합니다. videos.insert는 업로드당 기본 일일 예산의 약 16%인 1600단위의 비용이 들기 때문입니다. 업로드는 절대 재시도되지 않습니다: 결과를 알 수 없는 경우 부분 업로드가 있는지 확인할 수 있도록 보고되며 중복 게시를 방지합니다.

재생목록, 댓글, 동영상 관리는 구현된 쓰기 표면입니다. 분석 보고(0.8)는 로드맵에 있으며 아직 호출할 수 없습니다. 평가, 구독, 채널 설정 쓰기는 영구적으로 범위 밖으로 유지됩니다.

설정

npm 패키지는 아직 게시되지 않았으므로 서버는 클론에서 빌드하고 실행합니다. 순서대로 단계를 진행하세요.

1단계 — Node.js와 npm 확인

node -v
npm -v

node -v가 v20.17 이상을 출력하고 npm -v가 버전을 출력하면 3단계로 건너뛰세요. 두 명령 중 하나가 "command not found"를 보고하면 2단계를 계속하세요.

2단계 — Node.js와 npm 설치 (1단계가 실패한 경우에만)

npm은 Node.js와 함께 제공됩니다. Node를 설치하면 둘 다 설치됩니다. 플랫폼에 맞는 행을 하나 선택한 후 1단계를 다시 실행하여 확인하세요.

Node를 시스템 전체에 설치하고 싶지 않거나 여러 Node 버전을 나란히 사용해야 하는 경우 버전 관리자를 사용하세요:

# macOS and Linux
curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
nvm install 22
nvm use 22

Windows에서는 nvm-windows가 동일합니다: nvm install 22 후 nvm use 22.

설치 후 터미널을 닫고 다시 연 다음 node -v와 npm -v를 다시 실행하세요.

3단계 — 종속성 설치 및 빌드

git clone <repository-url>
cd "Youtube MCP"
npm ci
npm run build

npm ci는 package-lock.json의 정확한 버전을 설치합니다. npm install은 종속성을 변경하려는 경우에만 사용하세요. 빌드는 아래의 모든 명령이 호출하는 실행 파일을 dist/cli/index.js에 작성합니다.

빌드와 로컬 데이터 디렉터리를 확인하세요:

node dist/cli/index.js doctor

4단계 — Google 자격 증명 생성

아래의 모든 것은 자신의 Google Cloud 프로젝트에서 비롯됩니다. 이 프로젝트는 공유 Google 자격 증명을 제공하지 않습니다.

1. Google Cloud 콘솔에서 프로젝트를 만들거나 선택합니다.

2. 해당 프로젝트에 YouTube Data API v3를 사용 설정합니다.

3. API 키를 만듭니다 (사용자 인증 정보 → 사용자 인증 정보 만들기 → API 키). 이는 공개 읽기를 담당합니다.

4. OAuth 동의 화면을 구성합니다. 프로젝트가 테스트 상태인 동안 테스트 사용자 아래에 자신의 Google 계정을 추가하세요. 그렇지 않으면 login이 거부됩니다.

5. 데스크톱 앱 유형의 OAuth 클라이언트를 만든 다음 클라이언트 ID와 클라이언트 시크릿을 모두 복사합니다.

Google은 설치된 애플리케이션에서도 인증 코드 교환에 client_secret을 요구하므로, PKCE는 여기서 시크릿을 대체하는 것이 아니라 보완합니다.

5단계 — 서버에 필요한 자격 증명

총 4개의 자격 증명이 있습니다. 처음 세 개는 직접 제공하고, 네 번째는 login이 대신 얻습니다.

선택적 환경 변수: YOUTUBE_MCP_PROFILE (기본값 default), YOUTUBE_MCP_DATA_DIR, YOUTUBE_MCP_LOG_LEVEL (error, warn, info, debug). .env.example을 참조하세요.

이 중 어떤 것도 채팅 메시지, 공유 MCP 구성 파일, 또는 커밋될 명령에 붙여넣지 마세요. 대화형 프롬프트나 클라이언트의 환경/시크릿 주입 필드를 선호하세요.

6단계 — setup 실행 후 로그인

순서대로 실행하세요. setup은 프로필에 저장된 범위와 채널 ID를 다시 작성하므로 login 이후에 실행하면 해당 상태가 폐기되고 다시 로그인해야 합니다.

macOS 및 Linux:

YOUTUBE_OAUTH_CLIENT_ID="YOUR_DESKTOP_CLIENT_ID" \
  YOUTUBE_OAUTH_CLIENT_SECRET="YOUR_DESKTOP_CLIENT_SECRET" \
  node dist/cli/index.js setup
node dist/cli/index.js login
node dist/cli/index.js status

Windows PowerShell:

$env:YOUTUBE_OAUTH_CLIENT_ID  = "YOUR_DESKTOP_CLIENT_ID"
$env:YOUTUBE_OAUTH_CLIENT_SECRET = "YOUR_DESKTOP_CLIENT_SECRET"
node dist\cli\index.js setup
node dist\cli\index.js login
node dist\cli\index.js status
Remove-Item Env:\YOUTUBE_OAUTH_CLIENT_SECRET

시크릿을 셸 기록이나 프로세스 테이블에 전혀 넣지 않으려면 두 변수를 모두 생략하고 setup이 프롬프트하도록 하세요:

node dist/cli/index.js setup

setup은 터미널이 대화형일 때 누락된 각 값에 대해 프롬프트합니다.

login은 Google의 인증 페이지를 열고 PKCE S256과 임의의 state 값을 사용하여 127.0.0.1의 임의 루프백 포트를 통해 반환합니다. 프로필에 클라이언트 시크릿이 저장되어 있지 않으면 브라우저를 열기 전에 즉시 실패합니다.

저장된 자격 증명을 취소하고 제거하려면:

node dist/cli/index.js logout

7단계 — 서버 시작

YOUTUBE_API_KEY="your-api-key" node dist/cli/index.js serve

서버는 stdio를 통해 MCP를 사용하므로 일반적으로 수동이 아닌 클라이언트에 의해 실행됩니다. 사용 가능한 명령은 serve, doctor, status, setup, login, logout입니다.

로컬 데이터 위치

프로필, 할당량 원장, 초안, 작업 저널은 0700 디렉터리에 있습니다:

YOUTUBE_MCP_DATA_DIR로 재정의할 수 있습니다. 모든 로컬 상태를 제거하려면 logout을 실행한 다음 해당 디렉터리를 삭제하세요. 키체인 항목은 logout에 의해 제거됩니다.

클라이언트를 로컬 빌드에 연결

패키지가 게시될 때까지 클라이언트를 빌드된 dist/cli/index.js의 절대 경로로 지정하세요.

Claude Code

claude mcp add youtube --scope user \
  --env YOUTUBE_MCP_PROFILE=default \
  --env YOUTUBE_API_KEY=your-api-key -- \
  node /absolute/path/to/Youtube\ MCP/dist/cli/index.js serve

Claude Desktop

{
  "mcpServers": {
    "youtube": {
      "command": "node",
      "args": ["/absolute/path/to/Youtube MCP/dist/cli/index.js", "serve"],
      "env": {
        "YOUTUBE_MCP_PROFILE": "default",
        "YOUTUBE_API_KEY": "your-api-key"
      }
    }
  }
}

Codex

[mcp_servers.youtube]
command = "node"
args = ["/absolute/path/to/Youtube MCP/dist/cli/index.js", "serve"]

[mcp_servers.youtube.env]
YOUTUBE_MCP_PROFILE = "default"
YOUTUBE_API_KEY = "your-api-key"

변경 사항을 가져온 후 npm run build를 다시 실행하세요. 클라이언트는 src가 아닌 컴파일된 dist 출력을 실행합니다.

이 로컬 서버에 대한 Google 인증은 자체 setup 및 login 명령으로 수행됩니다. 클라이언트 수준의 MCP 로그인 명령은 다운스트림 Google OAuth 흐름을 대체하지 않습니다.

게시 후 클라이언트 구성

패키지가 릴리스되면 MCP 클라이언트가 예기치 않게 동작을 변경할 수 없도록 latest 대신 릴리스된 버전을 고정하세요.

Claude Desktop

{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "@youtube-mcp/server@0.7.0", "serve"],
      "env": {
        "YOUTUBE_MCP_PROFILE": "default"
      }
    }
  }
}

네이티브 Windows에서는 "command": "cmd"를 사용하고 인수 앞에 "/c", "npx"를 붙이세요.

Claude Code

claude mcp add youtube --scope user \
  --env YOUTUBE_MCP_PROFILE=default -- \
  npx -y @youtube-mcp/server@0.7.0 serve

Codex

codex mcp add youtube \
  --env YOUTUBE_MCP_PROFILE=default -- \
  npx -y @youtube-mcp/server@0.7.0 serve

동일한 Codex 구성:

[mcp_servers.youtube]
command = "npx"
args = ["-y", "@youtube-mcp/server@0.7.0", "serve"]

[mcp_servers.youtube.env]
YOUTUBE_MCP_PROFILE = "default"

한 번에 얼마나 추가할 수 있는지

도구 호출당 하드 스키마 제한:

따라서 단일 커밋의 상한은 50곡입니다. 더 긴 목록은 50곡 단위로 배치 커밋하여 처리합니다. 첫 번째 배치로 재생목록을 만든 다음, 이후 각 커밋에서 해당 target_playlist_id를 전달하여 항목을 추가합니다. 이미 존재하는 중복 항목은 건너뛰고 두 번 삽입하는 대신 보고됩니다.

실제로는 일일 할당량이 더 엄격한 제약입니다. Google의 프로젝트당 일일 기본 10,000단위를 기준으로, 50곡 실행 한 번의 비용은 대략 다음과 같습니다:

즉, 프로젝트당 하루에 약 50곡 재생목록 1개를 만들 수 있습니다. 같은 날 두 번째 전체 실행은 할당량을 소진하고 삽입 도중 실패합니다. 같은 목록을 두 번 준비하는 것은 특히 비용이 많이 듭니다. 답변이 변경되지 않았더라도 검색에 다시 비용이 청구되기 때문입니다.

할당량은 미국 태평양 시간 기준 자정에 재설정되며, 이는 로컬 원장이 사용하는 일 경계입니다.

할당량 기대치

youtube_quota_status는 로컬에서 관찰된 사용량을 보고하며, Google의 공식 잔액은 아닙니다. 일반 단위와 search.list 호출은 Google이 별도의 기본 일일 검색 호출 제한을 적용하므로 별도로 추적됩니다.

search.list는 게시된 100단위로 청구되므로 general_units는 실제 소비량을 반영합니다. 0.5.0 이전 릴리스는 이를 1단위로 기록하여 검색당 99단위만큼 사용량을 과소 보고했습니다. 보고된 수치가 여전히 낮아 보이는 동안 쓰기가 할당량으로 거부될 수 있습니다. 이전 빌드를 사용 중이라면 업그레이드하세요.

할당량 값은 변경될 수 있습니다. 구현 및 릴리스 작업은 이 README의 값을 영구 상수로 취급하는 대신 현재 공식 비용 표를 검증해야 합니다.

문제 해결

커밋이 completed가 비어 있고 모든 항목이 pending인 status: "partial"을 보고합니다. 재생목록이 생성되었지만 첫 번째 삽입이 거부되었습니다 — 대부분 일일 할당량 때문입니다. 맹목적인 재시도는 없으므로 중복 항목이 기록되지 않습니다. youtube_quota_status를 확인하고, 빈 재생목록을 삭제한 후 태평양 시간 재설정 후 다시 실행하세요. 초안은 일회용이므로 다시 실행하려면 새 youtube_prepare_music_playlist가 필요합니다.

브라우저가 열리기 전에 login이 실패합니다. 프로필에 클라이언트 시크릿이 저장되어 있지 않습니다. 먼저 setup을 실행하고 의도한 YOUTUBE_MCP_PROFILE에 있는지 확인하세요.

인증이 성공한 후 약 일주일 뒤에 작동이 중지됩니다. Testing 상태로 남아 있는 Google OAuth 프로젝트는 7일 후 만료되는 새로고침 토큰을 발급합니다. 동의 화면을 게시하거나 login을 다시 실행하세요.

공개 읽기에서 403 오류. 서버 환경에 YOUTUBE_API_KEY가 없습니다. 이 키는 영구 저장되지 않으므로 MCP 클라이언트 구성의 env 블록을 포함한 모든 실행에 존재해야 합니다.

인증 모델

• 공개 읽기는 프로세스 환경에 YOUTUBE_API_KEY가 필요합니다.

• 계정 읽기는 youtube.readonly 범위의 OAuth가 필요합니다.

• 재생목록 생성 및 댓글 쓰기는 Google이 재생목록 전용 범위를 제공하지 않으므로 youtube.force-ssl이 필요합니다.

• 비디오 업로드 및 수명 주기에는 youtube.upload가 필요합니다. 이는 별도로 요청되며, 이 범위 없이 인증된 프로필에서는 비디오 도구가 거부됩니다. 업로드 전에 동의 화면에 추가하고 login을 다시 실행하세요.

• 서버는 엄격한 엔드포인트 허용 목록으로 광범위한 Google 범위를 상쇄합니다. 재생목록 및 재생목록 항목 쓰기 엔드포인트만 호출할 수 있습니다.

• 설치된 애플리케이션은 Authorization Code + PKCE, 임의의 state, 그리고 임의 포트의 127.0.0.1 루프백 리디렉션을 사용합니다.

• 서비스 계정은 일반 YouTube 계정에서 지원되지 않습니다.

API 키, OAuth 클라이언트 데이터, 액세스 토큰, 새로고침 토큰, 로컬 데이터베이스, 디버그 로그 또는 .env 파일을 커밋하지 마세요.

자막 및 분석

일반 공개 트랜스크립트 검색은 v1에 포함되지 않습니다. 공식 자막 다운로드 엔드포인트는 권한 제한이 있고 비용이 많이 들므로 비공식 스크래핑은 사용하지 않습니다. 소유자 권한의 자막 관리는 나중에 고려될 수 있습니다.

YouTube Analytics 및 Reporting API도 연기되었습니다. 별도의 OAuth, 데이터 모델 및 운영 동작이 필요하며 초기 재생목록 중심 서버를 복잡하게 만들어서는 안 됩니다.

개발

구현 스택은 TypeScript, Node.js 20.17+, ESM, 공식 MCP TypeScript SDK, Zod 검증, 승인된 Google 엔드포인트에 대한 직접 타입 REST 호출, 로컬 할당량/초안/저널 상태를 위한 SQLite, OAuth 새로고침 토큰을 위한 OS 키체인 어댑터입니다.

현재 검사:

npm run format:check
npm run lint
npm run typecheck
npm test
npm run build

구현은 PLAN.md의 단계와 승인 게이트를 따라야 합니다. 에이전트별 제약 조건과 완료 정의는 AGENTS.md에 있습니다. Claude Code는 CLAUDE.md로 시작해야 합니다.

프로젝트 상태

• 제품 및 보안 아키텍처

• 저장소 개발 지침

• TypeScript 패키지 스캐폴드

• 공개 읽기 도구

• OAuth 및 프로필

• 음악 매칭 및 미리보기

• 확인된 새 재생목록 생성

• 미리보기된 재생목록 업데이트, 순서 변경, 제거 및 삭제

• 음악 초안 커밋을 위한 기존 재생목록 대상 (0.5)

• 할당량 원장의 올바른 search.list 일반 단위 회계 (0.5)

• 댓글 삽입, 답글, 삭제 및 중재 (0.6)

• 비디오 업로드, 메타데이터 업데이트, 삭제 및 썸네일 (0.7)

• YouTube Analytics 보고 (0.8)

• 클라이언트 간 통합 테스트

• 첫 npm 릴리스

라이선스

Apache License 2.0에 따라 라이선스가 부여됩니다. 전체 라이선스 텍스트는 LICENSE에 있습니다.

참고 자료

• Model Context Protocol

• YouTube Data API v3

• YouTube Data API 할당량 비용

• 설치된 앱용 Google OAuth

• Claude MCP 문서

• Codex MCP 문서