Spotify MCP Server
Spotify MCP 服务器
一个 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 凭据
点击 Create App
填写应用详情:
App name: 选择任意名称(例如 "My MCP Server")
App description: 可选
Redirect URI:
http://127.0.0.1:8888/callbackWhich 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 Secret |
| 否 |
| OAuth 重定向 URI |
身份验证
服务器使用 Spotify 的 授权码 (Authorization Code) 流程:
首次使用时,服务器会在您的浏览器中打开 Spotify 登录页面
Spotify 将要求您批准访问 — 服务器会请求完整工具集所需的所有范围(播放、资料库、播放列表和用户数据)
授权后,Spotify 会重定向到本地回调服务器
服务器将授权码交换为访问/刷新令牌
令牌安全地存储在
~/.spotify-mcp/credentials.json中令牌在过期时会自动刷新
如果在无头环境(SSH、Docker)中运行,授权 URL 将打印到 stderr — 请手动将其复制并粘贴到浏览器中。
重新身份验证
要重新身份验证(例如在撤销访问权限后),请删除存储的凭据:
rm ~/.spotify-mcp/credentials.json可用工具
搜索
工具 | 描述 |
| 搜索曲目、专辑、艺术家、播放列表、节目、剧集或有声读物 |
专辑
工具 | 描述 |
| 通过 ID 获取专辑详情 |
| 获取专辑中的曲目 |
艺术家
工具 | 描述 |
| 通过 ID 获取艺术家详情 |
| 获取艺术家的专辑 |
曲目
工具 | 描述 |
| 通过 ID 获取曲目详情 |
播放列表
工具 | 描述 |
| 获取播放列表详情 |
| 更新播放列表名称、描述或可见性 |
| 获取播放列表中的项目 |
| 向播放列表添加曲目/剧集 |
| 从播放列表中移除项目 |
| 重新排序播放列表中的项目 |
| 获取当前用户的播放列表 |
| 创建新播放列表 |
资料库
工具 | 描述 |
| 获取已保存的曲目 |
| 获取已保存的专辑 |
| 获取已保存的节目 |
| 获取已保存的剧集 |
| 获取已保存的有声读物 |
| 将项目保存到资料库 |
| 从资料库中移除项目 |
| 检查项目是否在资料库中 |
播放器
工具 | 描述 |
| 获取当前播放状态 |
| 获取当前正在播放的曲目 |
| 开始或恢复播放 |
| 暂停播放 |
| 跳到下一首曲目 |
| 跳到上一首曲目 |
| 定位到曲目中的位置 |
| 设置重复模式 (track/context/off) |
| 设置播放音量 |
| 切换随机播放模式 |
| 将播放转移到其他设备 |
| 获取可用设备 |
| 将项目添加到播放队列 |
| 获取播放队列 |
| 获取最近播放的曲目 |
节目与播客
工具 | 描述 |
| 获取节目详情 |
| 获取节目的剧集 |
有声读物
工具 | 描述 |
| 获取有声读物详情 |
| 获取有声读物的章节 |
| 获取章节详情 |
用户
工具 | 描述 |
| 获取当前用户的个人资料 |
| 获取热门艺术家或曲目 |
关注艺术家/用户使用相同的
save_to_library/remove_from_library/check_saved_in_library工具 — 传入艺术家或用户 URI。
贡献
请参阅 CONTRIBUTING.md 了解开发设置和指南。
许可证
MIT - 详情请参阅 LICENSE。
Available Tools
47 toolsadd_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
searchA
Search for tracks, albums, artists, playlists, shows, episodes, or audiobooks on Spotify.
Args:
query: Search query. Supports filters: artist:, album:, track:, year:, genre:,
isrc: (track ISRC), upc: (album UPC). Use NOT/OR with quotes for refinement.
types: Comma-separated types: track, album, artist, playlist, show, episode, audiobook.
limit: Maximum results per type (1-10, default 10).
offset: Index of first result to return (default 0).
market: ISO 3166-1 alpha-2 country code to filter results.
Inputs: query (required), limit, types, market, +1 more. 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
Scored across 47 tools
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.
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.
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.
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
Related MCP Connectors
Generate AI music via the Lacuna Music API from MCP clients like Claude Desktop & Code.
MCP server for progressive tool usage at any scale (see https://klavis.ai)
MCP server for Producer/Riffusion AI music generation
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that enables AI assistants like Claude to interact with Spotify, allowing them to search for tracks, control playback, and manage playlists.1ISC
- AlicenseAqualityDmaintenanceA Model Context Protocol server that enables AI assistants like Claude Desktop to interact with Spotify's music streaming service, supporting playback control, playlist management, music search, and user profile access.412MIT
- FlicenseNot gradedqualityDmaintenanceA FastMCP server that exposes Spotify's catalog and user context as tools for Claude, enabling track search, audio features, artist discography, recommendations, currently playing, and playlist creation.-
- FlicenseAqualityDmaintenanceA lightweight MCP server that enables AI assistants like Cursor and Claude to control Spotify playback, playlists, and manage tokens via OAuth.152-