ytm-runlist-mcp

Codex, Claude Code 같은 MCP 클라이언트에서 YouTube Music 플레이리스트를 러닝용으로 재배치하기 위한 로컬 MCP 서버입니다.

LLM이 곡 제목, 아티스트, 길이, 기존 순서를 보고 러닝 흐름을 판단하고, 이 서버는 YouTube Data API를 통해 실제 플레이리스트 조회/검증/생성을 담당합니다.

할 수 있는 일

• Google OAuth 로컬 로그인
• YouTube / YouTube Music 플레이리스트 목록 조회
• 선택한 플레이리스트 곡 목록 조회
• 러닝 페이스 전략 객관식 옵션 제공
• LLM이 만든 재배치 순서 검증
• 원본 플레이리스트 순서 변경
• 더 안전한 새 플레이리스트 복사본 생성

안전 원칙

• YouTube Music 비공식 스크래핑을 하지 않습니다.
• 음원을 다운로드하거나 스트리밍 오디오를 분석하지 않습니다.
• 캐시는 없습니다.
• 저장되는 개인 파일은 Google OAuth client secret과 token뿐입니다.
• 원본 플레이리스트 변경 tool은 기본값이 dry_run=true입니다.
• 실제 원본 변경은 dry_run=false와 confirm_modify_original=true가 모두 필요합니다.
• 기본 추천 흐름은 원본 수정이 아니라 새 비공개 플레이리스트 복사본 생성입니다.

프로젝트 구조

src/ytm_runlist_mcp/     MCP 서버와 YouTube API 코드
skills/                  선택형 Agent Skill 문서
tests/                   단위 테스트
.runlist/                로컬 OAuth 파일, git ignore 대상

준비물

• Python 3.11 이상
• YouTube / YouTube Music 플레이리스트가 있는 Google 계정
• Google Cloud 프로젝트
• YouTube Data API v3
• Codex, Claude Code, 또는 MCP 호환 클라이언트

1. Google Cloud Console 설정

1.1 프로젝트 만들기

1. Google Cloud Console을 엽니다: https://console.cloud.google.com/
2. 상단 프로젝트 선택 드롭다운을 클릭합니다.
3. New Project를 클릭합니다.
4. 프로젝트 이름을 입력합니다.

예시:

YTM Runlist MCP

생성 후 해당 프로젝트가 선택되어 있는지 확인합니다.

1.2 YouTube Data API v3 활성화

1. APIs & Services -> Library로 이동합니다.
2. 검색창에 입력합니다.

YouTube Data API v3

3. Enable을 클릭합니다.

YouTube Data API는 비공개 사용자 데이터 접근에 OAuth 2.0을 사용합니다. 또한 YouTube 계정에는 service account 방식이 맞지 않으므로, 이 프로젝트는 desktop installed app OAuth 흐름을 사용합니다.

1.3 OAuth 동의 화면 설정

Google Cloud UI에 따라 메뉴 이름이 조금 다를 수 있습니다.

새 UI:

Google Auth platform

예전 UI:

APIs & Services -> OAuth consent screen

설정:

App name: YTM Runlist MCP
User support email: 본인 이메일
Developer contact email: 본인 이메일
Audience / User type: External

개인용으로 쓸 때는 테스트 모드로 두면 됩니다.

1.4 Test user 추가

테스트 모드라면 YouTube Music을 쓰는 본인 Google 계정을 test user에 추가합니다.

Google Auth platform -> Audience -> Test users

1.5 Scope 추가

Data Access에서 아래 scope를 추가합니다.

https://www.googleapis.com/auth/youtube.force-ssl

이 scope는 플레이리스트 조회, 생성, 항목 추가, 순서 변경을 위해 사용합니다.

1.6 Desktop OAuth Client 생성

Google Auth platform -> Clients -> Create client

또는:

APIs & Services -> Credentials -> Create Credentials -> OAuth client ID

설정:

Application type: Desktop app
Name: YTM Runlist MCP Desktop

생성 후 JSON 파일을 다운로드합니다.

파일 이름은 보통 이런 형태입니다.

client_secret_1234567890-abcdef.apps.googleusercontent.com.json

2. macOS 설치

저장소를 받습니다.

git clone https://github.com/YOUR_USERNAME/ytm-runlist-mcp.git
cd ytm-runlist-mcp

가상환경을 만들고 설치합니다.

python3 -m venv .venv
. .venv/bin/activate
pip install -e ".[dev]"

Google Cloud에서 받은 OAuth JSON을 복사합니다.

mkdir -p .runlist
cp ~/Downloads/client_secret_*.json .runlist/client_secret.json

Google 계정 로그인을 실행합니다.

ytm-runlist-auth login
ytm-runlist-auth status

성공하면 대략 이렇게 보입니다.

{
  "client_secrets_exists": true,
  "token_exists": true,
  "valid_or_refreshable": true
}

3. Windows PowerShell 설치

저장소를 받습니다.

git clone https://github.com/YOUR_USERNAME/ytm-runlist-mcp.git
cd ytm-runlist-mcp

가상환경을 만들고 설치합니다.

py -3 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"

PowerShell이 스크립트 실행을 막으면 아래 명령을 한 번 실행합니다.

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

다시 활성화합니다.

.\.venv\Scripts\Activate.ps1

Google Cloud에서 받은 OAuth JSON을 복사합니다.

New-Item -ItemType Directory -Force .runlist
Copy-Item "$env:USERPROFILE\Downloads\client_secret_*.json" ".runlist\client_secret.json"

Google 계정 로그인을 실행합니다.

ytm-runlist-auth login
ytm-runlist-auth status

4. Codex에 MCP 등록

Codex 설정 파일에 MCP 서버를 추가합니다.

설정 파일:

~/.codex/config.toml

macOS 예시:

[mcp_servers.ytm-runlist]
command = "/ABSOLUTE/PATH/TO/ytm-runlist-mcp/.venv/bin/ytm-runlist-mcp"

[mcp_servers.ytm-runlist.env]
YTM_RUNLIST_DATA_DIR = "/ABSOLUTE/PATH/TO/ytm-runlist-mcp/.runlist"
GOOGLE_CLIENT_SECRETS_FILE = "/ABSOLUTE/PATH/TO/ytm-runlist-mcp/.runlist/client_secret.json"
YTM_RUNLIST_GOOGLE_TOKEN_FILE = "/ABSOLUTE/PATH/TO/ytm-runlist-mcp/.runlist/google-token.json"

Windows 예시:

[mcp_servers.ytm-runlist]
command = "C:\\ABSOLUTE\\PATH\\TO\\ytm-runlist-mcp\\.venv\\Scripts\\ytm-runlist-mcp.exe"

[mcp_servers.ytm-runlist.env]
YTM_RUNLIST_DATA_DIR = "C:\\ABSOLUTE\\PATH\\TO\\ytm-runlist-mcp\\.runlist"
GOOGLE_CLIENT_SECRETS_FILE = "C:\\ABSOLUTE\\PATH\\TO\\ytm-runlist-mcp\\.runlist\\client_secret.json"
YTM_RUNLIST_GOOGLE_TOKEN_FILE = "C:\\ABSOLUTE\\PATH\\TO\\ytm-runlist-mcp\\.runlist\\google-token.json"

Codex를 새로 열거나 새 세션을 시작합니다.

확인:

codex mcp list

5. Claude Code에 MCP 등록

Claude Code도 같은 MCP 서버를 사용할 수 있습니다. 서버를 따로 만들 필요는 없습니다.

macOS:

claude mcp add ytm-runlist \
  --env YTM_RUNLIST_DATA_DIR=/ABSOLUTE/PATH/TO/ytm-runlist-mcp/.runlist \
  --env GOOGLE_CLIENT_SECRETS_FILE=/ABSOLUTE/PATH/TO/ytm-runlist-mcp/.runlist/client_secret.json \
  --env YTM_RUNLIST_GOOGLE_TOKEN_FILE=/ABSOLUTE/PATH/TO/ytm-runlist-mcp/.runlist/google-token.json \
  -- /ABSOLUTE/PATH/TO/ytm-runlist-mcp/.venv/bin/ytm-runlist-mcp

Windows PowerShell:

claude mcp add ytm-runlist `
  --env YTM_RUNLIST_DATA_DIR="C:\ABSOLUTE\PATH\TO\ytm-runlist-mcp\.runlist" `
  --env GOOGLE_CLIENT_SECRETS_FILE="C:\ABSOLUTE\PATH\TO\ytm-runlist-mcp\.runlist\client_secret.json" `
  --env YTM_RUNLIST_GOOGLE_TOKEN_FILE="C:\ABSOLUTE\PATH\TO\ytm-runlist-mcp\.runlist\google-token.json" `
  -- "C:\ABSOLUTE\PATH\TO\ytm-runlist-mcp\.venv\Scripts\ytm-runlist-mcp.exe"

Claude Code는 MCP server scope를 지원합니다. 여러 프로젝트에서 쓰려면 --scope user, 팀과 공유하려면 project scope를 검토하세요.

6. 선택형 Skill

MCP 서버는 Skill 없이도 동작합니다.

다만 Skill을 쓰면 LLM이 더 일관된 순서로 작업합니다.

포함된 Skill:

skills/runlist-youtube-music/SKILL.md
skills/claude-code/runlist-youtube-music/SKILL.md

Skill의 역할:

1. 플레이리스트 목록 조회
2. 사용자에게 대상 선택 요청
3. 곡 목록 조회
4. 러닝 전략과 거리/시간 질문
5. 재배치 순서 검증
6. 쓰기 전 미리보기
7. 원본 수정 전 명시 확인
8. 기본적으로 새 비공개 복사본 생성 권장

7. 추천 프롬프트

Codex 또는 Claude Code에 그대로 붙여넣을 수 있습니다.

ytm-runlist MCP로 내 YouTube Music 플레이리스트를 러닝용으로 재배치해줘.

먼저 플레이리스트 목록을 보여주고, 내가 고르면 곡 목록을 확인해줘.
그다음 러닝 전략을 객관식으로 물어보고, 거리/목표 시간도 물어봐줘.

원본은 수정하지 말고, 재배치 미리보기 후 새 비공개 플레이리스트 복사본으로 만들어줘.
조회된 곡만 사용하고 playlist_item_id를 임의로 만들지 마.

8. MCP Tools

이 서버가 제공하는 tool:

health
get_running_strategy_options_tool
list_youtube_music_playlists
get_playlist_tracks_tool
validate_reorder_plan
reorder_original_playlist
create_reordered_playlist_copy_tool

9. 개발과 테스트

테스트 실행:

pytest

MCP 서버 직접 실행:

python -m ytm_runlist_mcp.server

stdio MCP 서버라서 터미널이 가만히 대기하는 것이 정상입니다.

10. YouTube Data API quota

YouTube Data API quota는 돈이 아니라 하루 API 사용량 제한입니다.

Google 공식 문서 기준으로 YouTube Data API를 활성화한 프로젝트는 기본적으로 search.list 100회/일, videos.insert 100회/일, 그 외 endpoint 합산 10,000 units/day를 받습니다. 이 프로젝트는 검색이나 영상 업로드를 쓰지 않고, 플레이리스트 조회/생성/항목 추가/순서 변경을 씁니다.

관련 quota cost 예시:

playlists.list       1 unit
playlistItems.list   1 unit
playlists.insert    50 units
playlistItems.insert 50 units
playlistItems.update 50 units

큰 플레이리스트를 자주 원본 재정렬하면 playlistItems.update가 곡 수만큼 호출되어 quota를 빨리 쓸 수 있습니다. quota를 다 쓰면 과금되는 것이 아니라 그날 더 이상 API 호출이 안 되고, 필요하면 YouTube API audit을 거쳐 quota 증설을 요청해야 합니다.

11. GitHub에 올리기 전 주의

아래 파일은 절대 커밋하지 마세요.

.runlist/
client_secret*.json
google-token.json
.env

현재 .gitignore에 포함되어 있습니다.

확인:

git status --ignored

12. 현재 한계

• YouTube Music 전용 공개 API가 아니라 YouTube Data API를 사용합니다.
• YouTube Music 플레이리스트가 YouTube Data API에서 보이는지 각자 계정으로 확인해야 합니다.
• 원본 플레이리스트 순서 변경은 playlistItems.update를 사용합니다.
• 플레이리스트가 수동 정렬 상태가 아니면 YouTube API가 순서 변경을 거부할 수 있습니다.
• 큰 플레이리스트는 dry-run으로 update 수를 먼저 확인하는 것이 좋습니다.

공식 문서

• Google OAuth consent setup: https://developers.google.com/workspace/guides/configure-oauth-consent
• YouTube Data API OAuth for installed apps: https://developers.google.com/youtube/v3/guides/auth/installed-apps
• YouTube Data API authentication: https://developers.google.com/youtube/v3/guides/authentication
• YouTube playlist item update: https://developers.google.com/youtube/v3/docs/playlistItems/update
• Codex MCP: https://developers.openai.com/codex/mcp
• Claude Code MCP: https://code.claude.com/docs/en/mcp
• Claude Code MCP quickstart: https://code.claude.com/docs/en/mcp-quickstart
• Claude Code skills: https://code.claude.com/docs/en/skills