controlling-spotify

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

1. Create Spotify Developer Application
2. Go to https://developer.spotify.com/dashboard/
3. Create an app and note the Client ID and Client Secret
4. Add redirect URI: http://127.0.0.1:8888/callback

1. Obtain Refresh Token
2. User must run the helper script locally (see references/setup-guide.md)
3. Script exchanges OAuth code for a long-lived refresh token
4. Refresh token is saved as credential in skill configuration

1. Configure Credentials
2. Add three credentials to this skill:
3. SPOTIFY_CLIENT_ID: From Spotify Developer Dashboard
4. SPOTIFY_CLIENT_SECRET: From Spotify Developer Dashboard
5. SPOTIFY_REFRESH_TOKEN: From helper script output

Alternative: Credentials can also be provided via a Project Knowledge file. Ensure the file contains a .env style block with the keys above.

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

1. searchSpotify - Search for tracks, albums, artists, or playlists

``python result = await client.call_tool("searchSpotify", { "query": "bohemian rhapsody", "type": "track", "limit": 10 }) ``

1. getNowPlaying - Get currently playing track information

``python result = await client.call_tool("getNowPlaying", {}) ``

1. getMyPlaylists - List user's playlists

``python result = await client.call_tool("getMyPlaylists", { "limit": 20, "offset": 0 }) ``

1. getPlaylistTracks - Get tracks from a playlist

``python result = await client.call_tool("getPlaylistTracks", { "playlistId": "37i9dQZEVXcJZyENOWUFo7" }) ``

1. getRecentlyPlayed - Get recently played tracks

``python result = await client.call_tool("getRecentlyPlayed", { "limit": 10 }) ``

1. getUsersSavedTracks - Get user's liked songs

``python result = await client.call_tool("getUsersSavedTracks", { "limit": 50, "offset": 0 }) ``

Playback Control

1. playMusic - Start playing track/album/artist/playlist

```python # 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" }) ```

1. pausePlayback - Pause current playback

``python result = await client.call_tool("pausePlayback", {}) ``

1. skipToNext - Skip to next track

``python result = await client.call_tool("skipToNext", {}) ``

1. skipToPrevious - Skip to previous track

``python result = await client.call_tool("skipToPrevious", {}) ``

1. addToQueue - Add track/album to playback queue

``python result = await client.call_tool("addToQueue", { "uri": "spotify:track:6rqhFgbbKwnb9MLmUQDhG6" }) ``

Playlist Management

1. createPlaylist - Create new playlist

``python result = await client.call_tool("createPlaylist", { "name": "My Workout Mix", "description": "High energy tracks", "public": False }) ``

1. addTracksToPlaylist - Add tracks to existing playlist

``python result = await client.call_tool("addTracksToPlaylist", { "playlistId": "3cEYpjA9oz9GiPac4AsH4n", "trackUris": [ "spotify:track:4iV5W9uYEdYUVa79Axb7Rh", "spotify:track:6rqhFgbbKwnb9MLmUQDhG6" ] }) ``

Album Operations

1. getAlbums - Get album details

``python result = await client.call_tool("getAlbums", { "albumIds": ["4aawyAB9vmqN3uQ7FjRGTy"] }) ``

1. getAlbumTracks - Get tracks from album

``python result = await client.call_tool("getAlbumTracks", { "albumId": "4aawyAB9vmqN3uQ7FjRGTy" }) ``

1. saveOrRemoveAlbumForUser - Save/remove albums

``python 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