spotify-mcp

MCP 서버로, spotipy를 감싸서 Claude(또는 모든 MCP 클라이언트)가 Spotify를 검색하고 플레이리스트, 저장된 트랙, 아티스트 카탈로그, 탐색 신호를 읽을 수 있게 합니다.

re-com의 Spotify 백엔드로 특별히 제작되었습니다. 설계상 읽기 중심이며, 재생 제어 서버가 아닙니다. 플레이리스트 생성과 트랙 추가는 지원하므로 re-com 추천 목록이 실제 플레이리스트가 될 수 있지만, 재생/일시정지/큐 제어는 없습니다. 그런 기능이 필요하다면 이미 있는 여러 재생 중심 Spotify MCP 서버 중 하나를 참고하세요.

도구

실제 제약을 분명히 말하자면: Spotify는 2024년 11월 이후 생성되었고 "Extended Quota Mode"(Spotify가 아주 드물게 승인하는 수동 승인)가 없는 API 앱에 대해 /recommendations 및 artist_related_artists를 제한합니다. 앱에 이 권한이 없으면 get_recommendations와 get_related_artists는 403을 반환합니다. handle_errors는 이를 원시 traceback 대신 명확한 메시지로 바꾸며, re-com의 spotify_client.py는 이를 치명적 오류가 아닌 하나의 신호를 사용할 수 없는 것으로 처리합니다. search_music, 플레이리스트, 저장된 트랙, 아티스트 인기 트랙은 영향을 받지 않습니다.

이 머신의 다른 Claude Code 프로젝트(예: re-com)는 spotipy/Spotify에 직접 통신하는 대신 MCP로 이 서버를 실행하여 이러한 도구를 호출합니다. 이곳이 Spotify 자격 증명이 존재하는 유일한 곳입니다.

설정

1. Spotify 앱 등록

1. Spotify Developer Dashboard로 이동하여 앱을 생성합니다.

2. SPOTIFY_REDIRECT_URI와 일치하는 리다이렉트 URI를 추가합니다(기본값은 http://127.0.0.1:8888/callback — 해당 포트에서 실제로 수신 대기 중인 것이 필요하지 않습니다. 3단계 참조).

3. 앱의 클라이언트 ID와 클라이언트 시크릿을 기록해 둡니다.

2. 의존성 설치

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

3. 인증

export SPOTIFY_CLIENT_ID="..."
export SPOTIFY_CLIENT_SECRET="..."
python scripts/setup_auth_spotify.py

이 명령은 인증 URL을 출력하고, 로그인 후 리다이렉트된 URL을 붙여넣기를 기다립니다(SSH/헤드리스 환경에서도 잘 동작합니다. 리다이렉트 포트를 바인딩할 필요가 없습니다). 그런 다음 결과 토큰을 .spotify_cache에 기록합니다(경로는 SPOTIFY_CACHE_PATH로 설정 가능).

.spotify_cache는 로그인한 세션과 동일하므로 커밋하거나 공유하지 마세요. 이미 gitignore에 포함되어 있습니다. 토큰은 한 번 캐시되면 자동으로 갱신됩니다. 갱신 자체가 실패하기 시작할 때(예: 앱의 클라이언트 시크릿이 교체되었거나 Spotify 계정 설정에서 액세스를 취소한 경우), 또는 server.py의 SCOPE에 새 권한이 추가된 경우에만 이 스크립트를 다시 실행하세요(먼저 .spotify_cache를 삭제해야 인증 흐름이 동의를 다시 요청합니다. 오래된 캐시 토큰은 새 scope를 자동으로 획득하지 못합니다).

4. Claude Code에 추가

claude mcp add spotify -s user \
  -e SPOTIFY_CLIENT_ID="..." \
  -e SPOTIFY_CLIENT_SECRET="..." \
  -e SPOTIFY_CACHE_PATH="$(pwd)/.spotify_cache" \
  -- "$(pwd)/.venv/bin/python" "$(pwd)/server.py"

-s user는 이 디렉터리뿐만 아니라 모든 Claude Code 세션에서 사용할 수 있게 합니다. 서버가 임의의 작업 디렉터리에서 실행될 수 있으므로 Python 인터프리터, server.py, SPOTIFY_CACHE_PATH에는 절대 경로를 사용하세요.

다른 MCP 클라이언트(Claude Desktop 등)의 경우 각 클라이언트의 구성 형식에 맞춰 동일한 명령과 환경 변수를 지정하세요.

테스트

단위 테스트 스위트(tests/)는 직접 만든 fake spotipy.Spotify 클라이언트로 실행되므로 네트워크 액세스나 Spotify 자격 증명이 필요 없습니다:

pip install -e ".[dev]"
pytest

오류 처리

도구 호출은 일반적인 실패 상황을 원시 traceback 대신 명확한 메시지로 변환합니다:

• 누락/만료된 인증(401) → 인증 단계를 다시 수행하라고 안내합니다.

• 제한/금지(403) → Spotify API 액세스 제한(위의 추천/관련 아티스트 주의사항 참조) 또는 누락된 OAuth scope 때문일 가능성이 높다고 안내합니다.

• 속도 제한(429) → Spotify가 보낸 경우 Retry-After 힌트를 포함하여 기다리라고 안내합니다.

• 다른 API 또는 OAuth 오류는 원시 traceback이 아닌 직접 보고됩니다.

라이선스

MIT — LICENSE 참조.