ytmusic-mcp

ytmusicapi를 감싸는 MCP 서버입니다. Claude(또는 모든 MCP 클라이언트)가 YouTube Music을 검색하고, 플레이리스트를 관리하며, 청취 기록을 읽을 수 있습니다.

도구

포함되지 않음(v1): BPM 기반 추천. YouTube Music은 템포 데이터를 노출하지 않으므로 두 번째 데이터 소스(예: 오디오 분석 API)가 필요합니다. 이는 향후 버전의 목표이며, 현재 빌드에는 포함되지 않습니다.

Related MCP server: mcp-server-youtube

설정

1. 의존성 설치

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

2. 인증

공식 YouTube Music API가 없으므로 ytmusicapi는 로그인된 브라우저 세션의 헤더를 재사용하여 인증합니다.

1. music.youtube.com을 Firefox(권장 — Chrome보다 원시 헤더 복사가 더 안정적임)에서 로그인 상태로 엽니다.

2. 개발자 도구 열기 (Cmd+Option+I / F12) → 네트워크 탭 → browse로 필터링.

3. 플레이리스트를 클릭하거나 페이지를 새로고침하여 browse POST 요청을 트리거합니다.

4. 해당 요청을 클릭 → 헤더 탭 → 원시 헤더 전환 → 전체 블록을 선택하여 복사합니다.

5. 프로젝트 루트에 raw_headers.txt라는 새 파일에 붙여넣고 저장합니다.

6. 다음을 실행합니다:

   python scripts/setup_auth_from_file.py

   이렇게 하면 headers_auth.json이 작성되고 raw_headers.txt가 삭제됩니다.

또는 python scripts/setup_auth.py를 실행하면 파일 대신 대화형 터미널 프롬프트를 통해 동일한 작업을 수행하므로 직접 붙여넣을 수 있습니다.

headers_auth.json은 로그인된 세션과 동일하므로 절대 커밋하거나 공유하지 마세요. 이미 gitignore에 포함되어 있습니다.

계속 진행하기 전에 인증이 작동하는지 확인합니다:

python scripts/test_search.py

이 헤더는 주기적으로 만료/교체됩니다. 도구가 인증 오류와 함께 실패하기 시작하면 이 단계를 다시 수행하세요.

3. Claude Code에 추가

claude mcp add ytmusic -s user \
  -e YTMUSIC_AUTH_PATH="$(pwd)/headers_auth.json" \
  -- "$(pwd)/.venv/bin/python" "$(pwd)/server.py"

-s user를 사용하면 이 디렉토리뿐만 아니라 모든 Claude Code 세션에서 사용할 수 있습니다. python 인터프리터, server.py, YTMUSIC_AUTH_PATH에는 절대 경로를 사용하세요. 서버가 어떤 작업 디렉토리에서도 실행될 수 있기 때문입니다.

다른 MCP 클라이언트(Claude Desktop 등)의 경우, 각각의 구성 형식을 사용하여 동일한 명령어와 환경 변수를 가리키도록 설정하세요.

오류 처리

도구 호출은 일반적인 실패 모드를 원시 추적 대신 명확한 메시지로 변환합니다:

• 인증 누락/만료/손상 → scripts/setup_auth_from_file.py를 다시 실행하라고 안내합니다.

• 속도 제한(HTTP 429) → 기다렸다가 다시 시도하라고 안내합니다.

• 차단/제한된 콘텐츠 → 충돌 대신 사용할 수 없다고 보고합니다.

• 네트워크 오류 → 직접 보고합니다.

라이선스

MIT — LICENSE를 참조하세요.