YouTube MCP Server

오소스 Model Context Protocol(MCP) 서버로, Claude Desktop, Claude Code, Codex와 같은 MCP 클라이언트에서 YouTube를 사용할 수 있게 합니다.

기본 워크플로는 다음과 같습니다.

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 지원.

계획된 v1 범위

읽기 도구

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

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

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

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

음악 재생목록 워크플로

• 준비 요청당 최대 50개의 구조화된 트랙을 허용합니다.

• 유력한 YouTube 뮤직비디오 일치 항목을 검색하고 순위를 매깁니다.

• 약한 일치 항목을 조용히 선택하는 대신 모호함과 대안을 보여줍니다.

• 명시적으로 선택된 일치 항목을 새 재생목록에 커밋합니다. 기존 재생목록 대상은 계획되어 있습니다.

• 새 재생목록의 기본값은 private입니다.

재생목록 관리

• 재생목록을 만들고 동영상을 추가합니다.

• 재생목록 메타데이터 또는 공개 범위를 업데이트합니다.

• 재생목록 항목을 재정렬하거나 제거합니다.

• 단기 유효하고 일회성인 확인 핸들이 발급된 후에만 재생목록을 삭제합니다.

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

재생목록 관리 외의 쓰기 작업(업로드, 댓글, 평가, 구독, 채널 변경)은 의도적으로 범위에서 제외됩니다.

설정

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 console에서 프로젝트를 만들거나 선택합니다.

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

3. API 키(사용자 인증 정보 → 사용자 인증 정보 만들기 → API 키)를 만듭니다. 이것은 공개 읽기를 처리합니다.

4. OAuth 동의 화면을 구서합니다. 프로젝트가 Testing 상태인 동안 Test users 아레에 자신의 Google 계정을 추가하세요. 그렇지 않으면 login이 거부됩니다.

5. Desktop app 유형의 OAuth client를 만든 다음 client ID와 client secret을 모두 복사하세요.

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은 프로필에 저장된 범위와 채널 정체성을 다시 작서하므로, login 후에 setup을 실해하면 해당 상태가 폐기되고 다시 로그인해야 합니다.

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

비밀을 hel 히스트리나 프로세스 테이블에 전혀 남기지 않으료면 두 변수를 모두 생략하고 setup이 프롬프트로 입렵받게 하세요:

node dist/cli/index.js setup

setup은 터미널이 대화형일 때 누락된 각 값을 프롬프트로 입력받습니다.

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

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

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"

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

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

게시 후 클라이언트 구성

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

Claude Desktop

{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "@youtube-mcp/server@0.4.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.4.0 serve

Codex

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

동등한 Codex 구성:

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

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

한 번에 얼마나 많이 추가할 수 있나요?

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

따라서 50곡이 한 번의 재생목록 생성 상한입니다. 준비된 초안은 아직 기존 재생목록에 커밋될 수 없으므로 50곡이 넘는 목록은 여러 개의 재생목록이 되어야 합니다.

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

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

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

할당량 기대치

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

[!WARNING] 알려진 제한 사항: 로컬 원장은 각 search.list를 일반 단위 1개와 검색 호출 1개로 기록하지만, Google은 여기에 100단위를 청구합니다. 검색을 많이 수행한 후에는 general_units가 검색당 실제 소비량을 99단위만큼 과소 보고하므로, 보고된 수치가 여전히 낮아 보여도 할당량으로 인해 쓰기가 거부될 수 있습니다. 이 문제가 수정될 때까지 search_calls 수를 의미 있는 신호로 취급하세요. 미리보기는 여전히 커밋의 쓰기 부분에 대한 estimated_commit_units 수치를 표시합니다.

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

문제 해결

커밋이 빈 completed와 모튠 항목이 pending인 status: "partial"을 보곳합니다. 재ȹ목록은 생성되었지만 첫 번재 삭입이 거부되었습니다 — 대부분 일일 할당량 때문입니다. 아무것도 무작정 재시도되지 않으므로 중복 항목이 작셩되지 않습니다. youtube_quota_status를 확인하고, 빈 재ȹ목록을 삭제한 후, 태평양 시간 재설정 후 다시 실핼하세요. 초안은 일회용이므로 재실핼하려면 새 youtube_prepare_music_playlist가 필욿합니다.

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

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

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

인증 모델

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

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

• 재생목록 생성에는 youtube.force-ssl이 필요합니다. Google은 재생목록 전용 범위를 제곱하지 않기 때문입니다.

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

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

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

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

자막 및 분석

일반 공개 대본 검색은 v1에 포합되지 않습니다. 공식 자막 다운로드 엔드포인트는 권한으로 제한되고 비용이 많이 들기 때문에 비공식 스크래핑은 사용되지 않습니다. 소유자가 승인한 자막 관리는 나중에 고려될 수 있습니다.

YouTube Analytics 및 Reporting API도 보류됩니다. 별도의 OAuth, 데이타 모델 및 운용 동작이 필욿하므로 초기 재생목록 중심 서버를 복잡하게 만어서는 안 됩니다.

개발

구현된 스택은 TypeScript, Node.j스 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는 CLAUD.md로 시작해야 합니다.

프로젝트 상태

• 제품 및 보안 아키텍처

• 리포지토리 개발 지침

• TypeScript 패키지 스폴드

• 공개 읽기 도구

• OAuth 및 프로필

• 음악 매칭 및 미리보기

• 확읶된 새 재생목록 생셩

• 미리보기된 재생목록 업데이트, 재정렬, 제거 및 삭제

• 음악 초안 커밋를 위한 기존 재생목록 대십

• 할당량 원장에서 search.list 일반 단위 회계 수정

• 교차 클라이언트 통합 테스트

• 첫 npm 릴리스

라이선스

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

참고 자료

• Model Context Protocol

• YouTube Data API v3

• YouTube Data API quota costs

• Google OAuth for installed apps

• Claude MCP documentation

• Codex MCP documentation