Skip to main content
Glama
Spotify MCP Server

Spotify MCP Server

by llyfn

Spotify MCP 서버

PyPI

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

기능

  • 검색 - 트랙, 앨범, 아티스트, 재생 목록, 쇼, 에피소드 및 오디오북 찾기

  • 재생 제어 - 재생, 일시 중지, 건너뛰기, 탐색, 볼륨, 셔플, 반복, 대기열 관리

  • 재생 목록 - 생성, 업데이트, 트랙 추가/제거/재정렬

  • 라이브러리 - 저장된 트랙, 앨범, 쇼, 에피소드 및 오디오북 보기 및 관리

  • 탐색 - 앨범 세부 정보, 아티스트 정보, 트랙 메타데이터 가져오기

  • 팟캐스트 및 오디오북 - 쇼, 에피소드, 오디오북 및 챕터 탐색

  • 사용자 프로필 - 프로필, 상위 아티스트/트랙, 팔로우 중인 아티스트 보기

  • 44개의 도구 - 더 이상 사용되지 않는(deprecated) 엔드포인트를 제외한 Spotify Web API 엔드포인트 지원

Related MCP server: Spotify MCP Server

사전 요구 사항

  • uv — curl -LsSf https://astral.sh/uv/install.sh | sh 명령어로 설치

  • Spotify 개발자 계정

  • Client ID와 Client Secret이 있는 Spotify 앱

Spotify 자격 증명 얻기

  1. Spotify 개발자 대시보드로 이동합니다.

  2. Create App을 클릭합니다.

  3. 앱 세부 정보를 입력합니다:

    • 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를 선택합니다.

  4. Save를 클릭합니다.

  5. 앱 페이지에서 Client ID를 찾습니다.

  6. 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 흐름을 사용합니다:

  1. 처음 사용할 때, 서버가 브라우저를 열어 Spotify 로그인 페이지로 이동합니다.

  2. Spotify가 액세스 승인을 요청합니다. 서버는 전체 도구 세트(재생, 라이브러리, 재생 목록 및 사용자 데이터)에 필요한 모든 범위를 요청합니다.

  3. 승인 후, Spotify는 로컬 콜백 서버로 리디렉션합니다.

  4. 서버는 인증 코드를 액세스/새로 고침 토큰으로 교환합니다.

  5. 토큰은 ~/.spotify-mcp/credentials.json에 안전하게 저장됩니다.

  6. 토큰은 만료되면 자동으로 새로 고쳐집니다.

헤드리스 환경(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를 참조하세요.

Available Tools

47 tools
add_playlist_itemsA

Add tracks or episodes to a playlist. Auto-chunks at 100 items per request.

    Args:
        playlist_id: The Spotify ID of the playlist.
        uris: List of Spotify URIs to add (e.g. ["spotify:track:xxx"]).
        position: Position to insert items (0-based). Appends to end if not specified.
            When chunking, subsequent chunks insert immediately after the previous.
    

Inputs: uris (required), playlist_id (required), position. Returns: result

add_to_queueA

Add a track or episode to the playback queue.

    Args:
        uri: Spotify URI of the item to add. E.g. "spotify:track:xxx".
        device_id: ID of the device. If not provided, uses the active device.
    

Inputs: uri (required), device_id. Returns: result

check_saved_in_libraryB

Check whether items are saved or artists/users/playlists are followed.

    Auto-chunks at 40 URIs per request.

    Args:
        uris: Spotify URIs: track, album, episode, show, audiobook, artist, user, or
            playlist (e.g. ["spotify:track:xxx", "spotify:artist:yyy"]).
    

Inputs: uris (required). Returns: result

create_playlistB

Create a new playlist for the current user.

    Args:
        name: Name for the new playlist.
        description: Description for the playlist.
        public: Whether the playlist should be public (default True).
    

Inputs: name (required), public, description. Returns: result

get_albumA

Get details of a Spotify album by its ID.

    Args:
        album_id: The Spotify ID of the album.
        market: ISO 3166-1 alpha-2 country code; affects availability/relinking.
    

Inputs: album_id (required), market. Returns: result

get_album_tracksA

Get tracks of a Spotify album.

    Args:
        album_id: The Spotify ID of the album.
        limit: Maximum number of tracks to return (1-50, default 20).
        offset: Index of the first track to return (default 0).
        market: ISO 3166-1 alpha-2 country code.
    

Inputs: album_id (required), limit, market, offset. Returns: result

get_artistA

Get details of a Spotify artist by their ID.

    Args:
        artist_id: The Spotify ID of the artist.
    

Inputs: artist_id (required). Returns: result

get_artist_albumsB

Get albums by a Spotify artist.

    Args:
        artist_id: The Spotify ID of the artist.
        include_groups: Comma-separated album types: album, single, appears_on, compilation.
        limit: Maximum number of albums to return (1-10, default 10).
        offset: Index of the first album to return (default 0).
        market: ISO 3166-1 alpha-2 country code.
    

Inputs: artist_id (required), limit, market, offset, +1 more. Returns: result

get_audiobookB

Get details of a Spotify audiobook.

    Args:
        audiobook_id: The Spotify ID of the audiobook.
        market: ISO 3166-1 alpha-2 country code.
    

Inputs: audiobook_id (required), market. Returns: result

get_audiobook_chaptersA

Get chapters of a Spotify audiobook.

    Args:
        audiobook_id: The Spotify ID of the audiobook.
        limit: Maximum number of chapters to return (1-50, default 20).
        offset: Index of the first chapter to return (default 0).
        market: ISO 3166-1 alpha-2 country code.
    

Inputs: audiobook_id (required), limit, market, offset. Returns: result

get_chapterA

Get details of a specific audiobook chapter.

    Args:
        chapter_id: The Spotify ID of the chapter.
        market: ISO 3166-1 alpha-2 country code.
    

Inputs: chapter_id (required), market. Returns: result

get_currently_playingB

Get the currently playing track or episode.

Inputs: no named parameters. Returns: result

get_devicesA

Get the user's available Spotify devices.

Inputs: no named parameters. Returns: result

get_episodeA

Get details of a podcast episode.

    Args:
        episode_id: The Spotify ID of the episode.
        market: ISO 3166-1 alpha-2 country code.
    

Inputs: episode_id (required), market. Returns: result

get_followed_artistsA

Get the current user's followed artists. Cursor-paginated.

    To follow or unfollow, use `save_to_library` / `remove_from_library` with Spotify URIs.

    Args:
        limit: Maximum number of artists to return (1-50, default 20).
        after: Cursor (last artist ID from previous page) to fetch the next page.
    

Inputs: after, limit. Returns: result

get_my_playlistsA

Get the current user's playlists.

    Args:
        limit: Maximum number of playlists to return (1-50, default 20).
        offset: Index of the first playlist to return (default 0).
    

Inputs: limit, offset. Returns: result

get_my_profileA

Get the current user's Spotify profile.

Inputs: no named parameters. Returns: result

get_my_top_itemsB

Get the current user's top artists or tracks.

    Args:
        item_type: Type of items: "artists" or "tracks" (default "tracks").
        time_range: "short_term" (~4wk), "medium_term" (~6mo), or "long_term" (all time).
        limit: Maximum number of items to return (1-50, default 20).
        offset: Index of the first item to return (default 0).
    

Inputs: limit, offset, item_type, time_range. Returns: result

get_playback_stateA

Get the current playback state including track, device, and progress.

Inputs: no named parameters. Returns: result

get_playlistA

Get details of a Spotify playlist.

    Shows playlist metadata plus the first 20 tracks. For more tracks or
    pagination, use `get_playlist_items`.

    Args:
        playlist_id: The Spotify ID of the playlist.
        market: ISO 3166-1 alpha-2 country code; affects track availability.
    

Inputs: playlist_id (required), market. Returns: result

get_playlist_itemsB

Get items (tracks/episodes) in a playlist.

    Args:
        playlist_id: The Spotify ID of the playlist.
        limit: Maximum number of items to return (1-50, default 20).
        offset: Index of the first item to return (default 0).
        market: ISO 3166-1 alpha-2 country code.
    

Inputs: playlist_id (required), limit, market, offset. Returns: result

get_queueB

Get the current playback queue.

Inputs: no named parameters. Returns: result

get_recently_playedB

Get the user's recently played tracks.

    Args:
        limit: Maximum number of items to return (1-50, default 20).
        after: Unix-ms cursor; return items played AFTER this timestamp.
        before: Unix-ms cursor; return items played BEFORE this timestamp.
            Only one of `after` / `before` may be set.
    

Inputs: after, limit, before. Returns: result

get_saved_albumsA

Get the current user's saved albums.

    Args:
        limit: Maximum number of albums to return (1-50, default 20).
        offset: Index of the first album to return (default 0).
    

Inputs: limit, offset. Returns: result

get_saved_audiobooksA

Get the current user's saved audiobooks.

    Args:
        limit: Maximum number of audiobooks to return (1-50, default 20).
        offset: Index of the first audiobook to return (default 0).
    

Inputs: limit, offset. Returns: result

get_saved_episodesA

Get the current user's saved episodes.

    Args:
        limit: Maximum number of episodes to return (1-50, default 20).
        offset: Index of the first episode to return (default 0).
    

Inputs: limit, offset. Returns: result

get_saved_showsA

Get the current user's saved shows (podcasts).

    Args:
        limit: Maximum number of shows to return (1-50, default 20).
        offset: Index of the first show to return (default 0).
    

Inputs: limit, offset. Returns: result

get_saved_tracksA

Get the current user's saved tracks.

    Args:
        limit: Maximum number of tracks to return (1-50, default 20).
        offset: Index of the first track to return (default 0).
    

Inputs: limit, offset. Returns: result

get_showA

Get details of a Spotify show (podcast).

    Args:
        show_id: The Spotify ID of the show.
        market: ISO 3166-1 alpha-2 country code; affects availability.
    

Inputs: show_id (required), market. Returns: result

get_show_episodesA

Get episodes of a Spotify show.

    Args:
        show_id: The Spotify ID of the show.
        limit: Maximum number of episodes to return (1-50, default 20).
        offset: Index of the first episode to return (default 0).
        market: ISO 3166-1 alpha-2 country code.
    

Inputs: show_id (required), limit, market, offset. Returns: result

get_trackA

Get details of a Spotify track by its ID.

    Args:
        track_id: The Spotify ID of the track.
        market: ISO 3166-1 alpha-2 country code; affects availability/relinking.
    

Inputs: track_id (required), market. Returns: result

next_trackA

Skip to the next track.

    Args:
        device_id: ID of the device. If not provided, uses the active device.
    

Inputs: device_id. Returns: result

pauseB

Pause playback on the active device.

    Args:
        device_id: ID of the device to pause. If not provided, pauses the active device.
    

Inputs: device_id. Returns: result

playA

Start or resume playback.

    Args:
        device_id: ID of the device to play on. Uses active device if omitted.
        context_uri: Spotify URI of context (album, artist, playlist).
        uris: List of Spotify track URIs to play. E.g. ["spotify:track:xxx"].
        offset_position: Position in the context to start playback (0-based index).
        position_ms: Position in milliseconds to seek to.
    

Inputs: uris, device_id, context_uri, position_ms, +1 more. Returns: result

previous_trackA

Skip to the previous track.

    Args:
        device_id: ID of the device. If not provided, uses the active device.
    

Inputs: device_id. Returns: result

remove_from_libraryA

Remove items from the user's library, or unfollow artists, users, and playlists.

    Auto-chunks at 40 URIs per request.

    Args:
        uris: Spotify URIs: track, album, episode, show, audiobook, artist, user, or
            playlist (e.g. ["spotify:track:xxx", "spotify:playlist:yyy"]).
    

Inputs: uris (required). Returns: result

remove_playlist_itemsA

Remove tracks or episodes from a playlist. Auto-chunks at 100 items per request.

    Args:
        playlist_id: The Spotify ID of the playlist.
        uris: List of Spotify URIs to remove (e.g. ["spotify:track:xxx"]).
    

Inputs: uris (required), playlist_id (required). Returns: result

reorder_playlist_itemsB

Reorder items in a playlist.

    Args:
        playlist_id: The Spotify ID of the playlist.
        range_start: Position of the first item to be reordered.
        insert_before: Position where the items should be inserted.
        range_length: Number of items to reorder (default 1).
    

Inputs: playlist_id (required), range_start (required), insert_before (required), range_length. Returns: result

save_to_libraryA

Save items to the user's library, or follow artists, users, and playlists.

    Auto-chunks at 40 URIs per request.

    Args:
        uris: Spotify URIs: track, album, episode, show, audiobook, artist, user, or
            playlist (e.g. ["spotify:track:xxx", "spotify:artist:yyy"]).
    

Inputs: uris (required). Returns: result

seekA

Seek to a position in the currently playing track.

    Args:
        position_ms: Position in milliseconds to seek to.
        device_id: ID of the device. If not provided, uses the active device.
    

Inputs: position_ms (required), device_id. Returns: result

set_repeatA

Set the repeat mode for playback.

    Args:
        state: Repeat mode: "track", "context", or "off".
        device_id: ID of the device. If not provided, uses the active device.
    

Inputs: state (required), device_id. Returns: result

set_volumeA

Set the playback volume.

    Args:
        volume_percent: Volume level (0-100).
        device_id: ID of the device. If not provided, uses the active device.
    

Inputs: volume_percent (required), device_id. Returns: result

toggle_shuffleA

Set or toggle shuffle mode for playback.

    Args:
        state: True to enable, False to disable. If omitted, flips the current state.
        device_id: ID of the device. If not provided, uses the active device.
    

Inputs: state, device_id. Returns: result

transfer_playbackA

Transfer playback to a different device.

    Args:
        device_id: ID of the device to transfer to.
        play: Whether to start playing on the new device (default True).
    

Inputs: device_id (required), play. Returns: result

update_playlistB

Update a playlist's name, description, or visibility.

    Args:
        playlist_id: The Spotify ID of the playlist.
        name: New name for the playlist.
        description: New description for the playlist.
        public: Whether the playlist should be public.
    

Inputs: playlist_id (required), name, public, description. Returns: result

whoamiA

Diagnostic: show auth status, profile basics, active device, and configured scopes.

Inputs: no named parameters. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 47 tools

    Disambiguation4/5

    Tools target distinct resources and actions, but there are minor overlaps: get_playlist vs get_playlist_items and get_playback_state vs get_currently_playing could be confused, though descriptions clarify the differences.

    Naming Consistency4/5

    Mostly consistent snake_case with verb_noun (get_track, add_playlist_items), but some tools are single imperatives (play, pause, search) or use an adjective_noun form (next_track), slightly breaking the pattern.

    Tool Count2/5

    With 47 tools, the server far exceeds the recommended 3-15 range and crosses the 25+ threshold for 'too many', making it heavy and potentially overwhelming despite the broad Spotify domain.

    Completeness4/5

    Core CRUD for playlists, library, and playback is covered, but notable gaps remain such as no delete_playlist and no access to recommendations, audio features, or artist top tracks—minor omissions agents can work around.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers