Spotify MCP 서버

PyPI

Spotify Web API와 상호 작용하기 위한 도구를 제공하는 Model Context Protocol (MCP) 서버입니다. Claude와 같은 AI 어시스턴트가 음악 검색, 재생 제어, 재생 목록 관리 등을 수행할 수 있도록 합니다.

기능

검색 - 트랙, 앨범, 아티스트, 재생 목록, 쇼, 에피소드 및 오디오북 찾기
재생 제어 - 재생, 일시 중지, 건너뛰기, 탐색, 볼륨, 셔플, 반복, 대기열 관리
재생 목록 - 생성, 업데이트, 트랙 추가/제거/재정렬
라이브러리 - 저장된 트랙, 앨범, 쇼, 에피소드 및 오디오북 보기 및 관리
탐색 - 앨범 세부 정보, 아티스트 정보, 트랙 메타데이터 가져오기
팟캐스트 및 오디오북 - 쇼, 에피소드, 오디오북 및 챕터 탐색
사용자 프로필 - 프로필, 상위 아티스트/트랙, 팔로우 중인 아티스트 보기
44개의 도구 - 더 이상 사용되지 않는(deprecated) 엔드포인트를 제외한 Spotify Web API 엔드포인트 지원

사전 요구 사항

uv — curl -LsSf https://astral.sh/uv/install.sh | sh 명령어로 설치
Spotify 개발자 계정
Client ID와 Client Secret이 있는 Spotify 앱

Spotify 자격 증명 얻기

Spotify 개발자 대시보드로 이동합니다.
Create App을 클릭합니다.
앱 세부 정보를 입력합니다:
- App name: 원하는 이름 선택 (예: "My MCP Server")
- App description: 선택 사항
- Redirect URI: http://127.0.0.1:8888/callback
- Which API/SDKs are you planning to use?: Web API를 선택합니다.
Save를 클릭합니다.
앱 페이지에서 Client ID를 찾습니다.
Show client secret을 클릭하여 Client Secret을 확인합니다.

중요: 리디렉션 URI는 http://127.0.0.1:8888/callback과 정확히 일치해야 합니다(또는 SPOTIFY_REDIRECT_URI에 설정한 값). localhost를 사용하지 말고 127.0.0.1을 사용하세요.

설치

아래에서 클라이언트를 선택하세요. 모든 예제는 uvx를 사용하여 필요할 때 서버를 가져오므로 복제나 수동 설치가 필요 없습니다.

Claude Code

claude mcp add spotify \
  -e SPOTIFY_CLIENT_ID=your_client_id \
  -e SPOTIFY_CLIENT_SECRET=your_client_secret \
  -- uvx mcp-server-spotify

기타 MCP 클라이언트

대부분의 MCP 클라이언트는 JSON 파일을 통해 서버를 구성합니다. 클라이언트의 MCP 구성에 다음 항목을 추가하세요:

{
  "mcpServers": {
    "spotify": {
      "command": "uvx",
      "args": ["mcp-server-spotify"],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id",
        "SPOTIFY_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

로컬 체크아웃에서 실행

개발용이거나 수정된 복사본을 실행하려는 경우:

git clone https://github.com/llyfn/spotify-mcp.git
cd spotify-mcp && uv sync

그런 다음 uvx 대신 로컬 체크아웃을 가리키도록 클라이언트를 설정하세요:

"command": "uv",
"args": ["--directory", "/absolute/path/to/spotify-mcp", "run", "mcp-server-spotify"]

구성

변수	필수	기본값	설명
`SPOTIFY_CLIENT_ID`	예	—	Spotify 앱의 Client ID
`SPOTIFY_CLIENT_SECRET`	예	—	Spotify 앱의 Client Secret
`SPOTIFY_REDIRECT_URI`	아니요	`http://127.0.0.1:8888/callback`	OAuth 리디렉션 URI

인증

이 서버는 Spotify의 Authorization Code 흐름을 사용합니다:

처음 사용할 때, 서버가 브라우저를 열어 Spotify 로그인 페이지로 이동합니다.
Spotify가 액세스 승인을 요청합니다. 서버는 전체 도구 세트(재생, 라이브러리, 재생 목록 및 사용자 데이터)에 필요한 모든 범위를 요청합니다.
승인 후, Spotify는 로컬 콜백 서버로 리디렉션합니다.
서버는 인증 코드를 액세스/새로 고침 토큰으로 교환합니다.
토큰은 ~/.spotify-mcp/credentials.json에 안전하게 저장됩니다.
토큰은 만료되면 자동으로 새로 고쳐집니다.

헤드리스 환경(SSH, Docker)에서 실행 중인 경우, 인증 URL이 stderr로 출력됩니다. 이를 복사하여 브라우저에 수동으로 붙여넣으세요.

재인증

재인증(예: 액세스 권한 취소 후)하려면 저장된 자격 증명을 삭제하세요:

rm ~/.spotify-mcp/credentials.json

사용 가능한 도구

검색

도구	설명
`search`	트랙, 앨범, 아티스트, 재생 목록, 쇼, 에피소드 또는 오디오북 검색

앨범

도구	설명
`get_album`	ID로 앨범 세부 정보 가져오기
`get_album_tracks`	앨범의 트랙 가져오기

아티스트

도구	설명
`get_artist`	ID로 아티스트 세부 정보 가져오기
`get_artist_albums`	아티스트의 앨범 가져오기

트랙

도구	설명
`get_track`	ID로 트랙 세부 정보 가져오기

재생 목록

도구	설명
`get_playlist`	재생 목록 세부 정보 가져오기
`update_playlist`	재생 목록 이름, 설명 또는 공개 여부 업데이트
`get_playlist_items`	재생 목록의 항목 가져오기
`add_playlist_items`	재생 목록에 트랙/에피소드 추가
`remove_playlist_items`	재생 목록에서 항목 제거
`reorder_playlist_items`	재생 목록의 항목 재정렬
`get_my_playlists`	현재 사용자의 재생 목록 가져오기
`create_playlist`	새 재생 목록 생성

라이브러리

도구	설명
`get_saved_tracks`	저장된 트랙 가져오기
`get_saved_albums`	저장된 앨범 가져오기
`get_saved_shows`	저장된 쇼 가져오기
`get_saved_episodes`	저장된 에피소드 가져오기
`get_saved_audiobooks`	저장된 오디오북 가져오기
`save_to_library`	라이브러리에 항목 저장
`remove_from_library`	라이브러리에서 항목 제거
`check_saved_in_library`	라이브러리에 항목이 있는지 확인

플레이어

도구	설명
`get_playback_state`	현재 재생 상태 가져오기
`get_currently_playing`	현재 재생 중인 트랙 가져오기
`play`	재생 시작 또는 재개
`pause`	재생 일시 중지
`next_track`	다음 트랙으로 건너뛰기
`previous_track`	이전 트랙으로 건너뛰기
`seek`	트랙 내 위치 탐색
`set_repeat`	반복 모드 설정 (트랙/컨텍스트/끄기)
`set_volume`	재생 볼륨 설정
`toggle_shuffle`	셔플 모드 전환
`transfer_playback`	다른 기기로 재생 전송
`get_devices`	사용 가능한 기기 가져오기
`add_to_queue`	재생 대기열에 항목 추가
`get_queue`	재생 대기열 가져오기
`get_recently_played`	최근 재생한 트랙 가져오기

쇼 및 팟캐스트

도구	설명
`get_show`	쇼 세부 정보 가져오기
`get_show_episodes`	쇼의 에피소드 가져오기

오디오북

도구	설명
`get_audiobook`	오디오북 세부 정보 가져오기
`get_audiobook_chapters`	오디오북의 챕터 가져오기
`get_chapter`	챕터 세부 정보 가져오기

사용자

도구	설명
`get_my_profile`	현재 사용자의 프로필 가져오기
`get_my_top_items`	상위 아티스트 또는 트랙 가져오기

아티스트/사용자 팔로우는 동일한 save_to_library / remove_from_library / check_saved_in_library 도구를 사용합니다. 아티스트 또는 사용자 URI를 전달하세요.

기여

개발 설정 및 지침은 CONTRIBUTING.md를 참조하세요.

라이선스

MIT - 자세한 내용은 LICENSE를 참조하세요.

mcp-server-spotify