Controlling Spotify
Control Spotify playback, search for music, and manage playlists using the Spotify MCP Server with full user account access.
When to Use
Invoke this skill when users request:
- Playing, pausing, or skipping music on Spotify
- Searching for songs, albums, artists, or playlists
- Creating or modifying playlists
- Viewing currently playing track or playback status
- Managing their Spotify library (saved tracks, albums)
- Queuing songs or albums
Prerequisites
CRITICAL: This skill requires user-provided credentials. The user must complete a one-time setup:
One-Time User Setup
-
Create Spotify Developer Application
- Go to https://developer.spotify.com/dashboard/
- Create an app and note the Client ID and Client Secret
- Add redirect URI:
http://127.0.0.1:8888/callback
-
Obtain Refresh Token
- User must run the helper script locally (see
references/setup-guide.md) - Script exchanges OAuth code for a long-lived refresh token
- Refresh token is saved as credential in skill configuration
- User must run the helper script locally (see
-
Configure Credentials
- Add three credentials to this skill:
SPOTIFY_CLIENT_ID: From Spotify Developer DashboardSPOTIFY_CLIENT_SECRET: From Spotify Developer DashboardSPOTIFY_REFRESH_TOKEN: From helper script output
Alternative: Credentials can also be provided via a Project Knowledge file. Ensure the file contains a
.envstyle block with the keys above. - Add three credentials to this skill:
Without these credentials, the skill cannot function. If credentials are missing, guide the user through the setup process detailed in references/setup-guide.md.
MCP Server Installation
The Spotify MCP Server must be installed in the compute environment. Use the provided installation script which handles cloning, patching, and building the server.
# Run the installation script
bash scripts/install-mcp-server.sh
MCP Server Configuration
Configure the MCP client to connect to the Spotify MCP server. Note the logic to support credentials from Project Knowledge.
from mcp import Client
import asyncio
import re
# 1. Try to get credentials from skill configuration
env_vars = {
"SPOTIFY_CLIENT_ID": credentials.get("SPOTIFY_CLIENT_ID"),
"SPOTIFY_CLIENT_SECRET": credentials.get("SPOTIFY_CLIENT_SECRET"),
"SPOTIFY_REFRESH_TOKEN": credentials.get("SPOTIFY_REFRESH_TOKEN")
}
# 2. If missing, look in Project Knowledge / Context for .env style block
if not all(env_vars.values()):
# Heuristic: Scan context/files for VAR=VALUE patterns
# (Pseudo-code: Implement based on available context access)
pass
# Server configuration
mcp_config = {
"command": "node",
"args": ["/home/claude/spotify-mcp-server/build/index.js"],
"env": env_vars
}
# Initialize client
async def initialize_spotify_mcp():
client = Client()
await client.connect_stdio(
mcp_config["command"],
mcp_config["args"],
mcp_config["env"]
)
return client
Available Tools
Read Operations
-
searchSpotify - Search for tracks, albums, artists, or playlists
result = await client.call_tool("searchSpotify", { "query": "bohemian rhapsody", "type": "track", "limit": 10 }) -
getNowPlaying - Get currently playing track information
result = await client.call_tool("getNowPlaying", {}) -
getMyPlaylists - List user's playlists
result = await client.call_tool("getMyPlaylists", { "limit": 20, "offset": 0 }) -
getPlaylistTracks - Get tracks from a playlist
result = await client.call_tool("getPlaylistTracks", { "playlistId": "37i9dQZEVXcJZyENOWUFo7" }) -
getRecentlyPlayed - Get recently played tracks
result = await client.call_tool("getRecentlyPlayed", { "limit": 10 }) -
getUsersSavedTracks - Get user's liked songs
result = await client.call_tool("getUsersSavedTracks", { "limit": 50, "offset": 0 })
Playback Control
-
playMusic - Start playing track/album/artist/playlist
# Play by URI result = await client.call_tool("playMusic", { "uri": "spotify:track:6rqhFgbbKwnb9MLmUQDhG6" }) # Or by type and ID result = await client.call_tool("playMusic", { "type": "track", "id": "6rqhFgbbKwnb9MLmUQDhG6" }) -
pausePlayback - Pause current playback
result = await client.call_tool("pausePlayback", {}) -
skipToNext - Skip to next track
result = await client.call_tool("skipToNext", {}) -
skipToPrevious - Skip to previous track
result = await client.call_tool("skipToPrevious", {}) -
addToQueue - Add track/album to playback queue
result = await client.call_tool("addToQueue", { "uri": "spotify:track:6rqhFgbbKwnb9MLmUQDhG6" })
Playlist Management
-
createPlaylist - Create new playlist
result = await client.call_tool("createPlaylist", { "name": "My Workout Mix", "description": "High energy tracks", "public": False }) -
addTracksToPlaylist - Add tracks to existing playlist
result = await client.call_tool("addTracksToPlaylist", { "playlistId": "3cEYpjA9oz9GiPac4AsH4n", "trackUris": [ "spotify:track:4iV5W9uYEdYUVa79Axb7Rh", "spotify:track:6rqhFgbbKwnb9MLmUQDhG6" ] })
Album Operations
-
getAlbums - Get album details
result = await client.call_tool("getAlbums", { "albumIds": ["4aawyAB9vmqN3uQ7FjRGTy"] }) -
getAlbumTracks - Get tracks from album
result = await client.call_tool("getAlbumTracks", { "albumId": "4aawyAB9vmqN3uQ7FjRGTy" }) -
saveOrRemoveAlbumForUser - Save/remove albums
result = await client.call_tool("saveOrRemoveAlbumForUser", { "albumIds": ["4aawyAB9vmqN3uQ7FjRGTy"], "action": "save" })
Workflow Examples
Example 1: Play User's Favorite Song
# 1. Search for the song
search_result = await client.call_tool("searchSpotify", {
"query": "user's favorite song name",
"type": "track",
"limit": 1
})
# 2. Extract track URI from results
track_uri = search_result["tracks"][0]["uri"]
# 3. Play the track
await client.call_tool("playMusic", {
"uri": track_uri
})
Example 2: Create Playlist from Genre
# 1. Search for tracks in genre
search_result = await client.call_tool("searchSpotify", {
"query": "genre:rock year:2020-2024",
"type": "track",
"limit": 20
})
# 2. Create new playlist
playlist_result = await client.call_tool("createPlaylist", {
"name": "Modern Rock Mix",
"description": "Recent rock tracks",
"public": False
})
# 3. Extract track URIs
track_uris = [track["uri"] for track in search_result["tracks"]]
# 4. Add tracks to playlist
await client.call_tool("addTracksToPlaylist", {
"playlistId": playlist_result["id"],
"trackUris": track_uris
})
Example 3: Show What's Playing
# Get current playback state
now_playing = await client.call_tool("getNowPlaying", {})
# Format and display
print(f"Now Playing: {now_playing['track']['name']}")
print(f"Artist: {now_playing['track']['artists'][0]['name']}")
print(f"Album: {now_playing['track']['album']['name']}")
print(f"Progress: {now_playing['progress_ms']} / {now_playing['duration_ms']} ms")
Important Notes
Spotify Premium Required
Playback control operations (play, pause, skip, queue) require Spotify Premium. Read operations (search, get playlists, view tracks) work with free accounts.
Active Device Required
For playback commands to work, the user must have an active Spotify session (web player, deskt