/controlling-spotify

name: controlling-spotify
description: Control Spotify playback and manage playlists via MCP server. Use when user requests playing music, controlling Spotify, creating playlists, searching songs, or managing their Spotify library.
credentials:
- SPOTIFY_CLIENT_ID
- SPOTIFY_CLIENT_SECRET
- SPOTIFY_REFRESH_TOKEN
domains:
- api.spotify.com
- accounts.spotify.com
- raw.githubusercontent.com
- github.com
metadata:
  version: 0.1.0

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**

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

2. **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

3. **Configure Credentials**

• Add three credentials to this skill:
• `SPOTIFY_CLIENT_ID`: From Spotify Developer Dashboard
• `SPOTIFY_CLIENT_SECRET`: From Spotify Developer Dashboard
• `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

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

2. **getNowPlaying** - Get currently playing track information

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

3. **getMyPlaylists** - List user's playlists

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

4. **getPlaylistTracks** - Get tracks from a playlist

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

5. **getRecentlyPlayed** - Get recently played tracks

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

6. **getUsersSavedTracks** - Get user's liked songs

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

Playback Control

1. **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"
   })

2. **pausePlayback** - Pause current playback

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

3. **skipToNext** - Skip to next track

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

4. **skipToPrevious** - Skip to previous track

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

5. **addToQueue** - Add track/album to playback queue

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

Playlist Management

1. **createPlaylist** - Create new playlist

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

2. **addTracksToPlaylist** - Add tracks to existing playlist

   result = await client.call_tool("addTracksToPlaylist", {
       "playlistId": "3cEYpjA9oz9GiPac4AsH4n",
       "trackUris": [
           "spotify:track:4iV5W9uYEdYUVa79Axb7Rh",
           "sp