Skip to main content
Glama
Spotify MCP Server

Spotify MCP Server

by llyfn

Spotify MCP 服务器

PyPI

一个 Model Context Protocol (MCP) 服务器,提供与 Spotify Web API 交互的工具。使 Claude 等 AI 助手能够搜索音乐、控制播放、管理播放列表等。

功能

  • 搜索 - 查找曲目、专辑、艺术家、播放列表、节目、剧集和有声读物

  • 播放控制 - 播放、暂停、跳过、定位、音量、随机播放、重复播放、队列管理

  • 播放列表 - 创建、更新、添加/移除/重新排序曲目

  • 资料库 - 查看和管理已保存的曲目、专辑、节目、剧集和有声读物

  • 浏览 - 获取专辑详情、艺术家信息、曲目元数据

  • 播客与有声读物 - 浏览节目、剧集、有声读物和章节

  • 用户个人资料 - 查看个人资料、热门艺术家/曲目、关注的艺术家

  • 44 个工具 涵盖了非弃用的 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

设置重复模式 (track/context/off)

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