tylerpina/spotify-mcp

Spotify MCP Server

Connect your Spotify account to AI tools and automate your music experience with the Model Context Protocol (MCP).

The Spotify MCP Server implements the Model Context Protocol to bridge your Spotify account with AI-powered tools like Cursor, Claude, VS Code, and more. It enables AI models to search, analyze, and manage your Spotify music library, playlists, and playback through natural language instructions.

✨ Key Features

• 🎵 Music Search & Discovery: Find tracks, albums, artists, playlists, shows, and episodes
• 📝 Playlist Management: View, create, update, reorder, and manage playlists
• 📚 User Library Access: Access and modify your saved tracks, albums, and shows
• 🎯 Personalized Recommendations: Get music suggestions based on your taste
• 📊 Audio Analysis: Retrieve audio features (danceability, energy, tempo, etc.) for tracks
• 🎧 Playback Control: (Premium only) Play, pause, skip, and control playback devices
• 📈 User Insights: View your top tracks, artists, and listening history
• 🔄 Queue Management: Add tracks to your queue and view upcoming songs
• 📱 Device Management: Transfer playback between devices

🚀 Quickstart Guide

Prerequisites

• A Spotify account (Premium required for playback control)
• Spotify API credentials (see below)
• Node.js 18 or newer

Step 1: Get Spotify API Credentials

1. Go to the Spotify Developer Dashboard
2. Create a new application
3. Note your Client ID and Client Secret
4. Set the Redirect URI to: http://127.0.0.1:8000/callback

Step 2: Set Environment Variables

Create a .env file in your project root:

SPOTIFY_CLIENT_ID=your-client-id
SPOTIFY_CLIENT_SECRET=your-client-secret
SPOTIFY_REDIRECT_URI=http://127.0.0.1:8000/callback

Note: You no longer need to manually obtain access tokens! The server will handle the OAuth flow automatically.

Step 3: Install and Run

# Install dependencies
npm install

# Build the server
npm run build

# Start the server
npm start

Step 4: Connect from Your AI Tool

Add this configuration to your MCP-compatible application (example for Cursor):

{
  "mcpServers": {
    "spotify": {
      "command": "npx",
      "args": ["-y", "@tdp2003/spotify-mcp@latest"],
      "env": {
        "SPOTIFY_CLIENT_ID": "your-client-id",
        "SPOTIFY_CLIENT_SECRET": "your-client-secret",
        "SPOTIFY_REDIRECT_URI": "http://127.0.0.1:8000/callback"
      }
    }
  }
}

Step 5: Complete Authorization

1. Call the get_initial_context tool in your AI application
2. If not already authorized, you'll receive an authorization URL
3. Open the URL in your browser and log in to Spotify
4. Authorize the application - you'll be redirected automatically
5. Call get_initial_context again to confirm the connection

🛠️ Available Tools

⚠️ Important: Always call get_initial_context first to initialize your Spotify connection before using any other tools.

🔧 Context & Setup

get_initial_context

Required first step - Initializes your Spotify connection and provides usage instructions. This tool must be called before any other operations.

What it does:

• Validates your Spotify API credentials
• Initiates OAuth flow if needed
• Retrieves your user profile and account information
• Provides connection status and available features
• Returns usage instructions for the AI assistant

📝 Playlist Operations

get_user_playlists

Retrieve playlists for the current user or a specific user.

Parameters:

• limit (optional): Number of playlists to return (1-50, default: 20)
• offset (optional): Index of the first playlist to return (default: 0)
• userId (optional): User ID to get playlists for (defaults to current user)

Returns: Playlist metadata including name, description, track count, privacy settings, and owner information.

create_playlist

Create a new playlist with customizable settings.

Parameters:

• name (required): Playlist name
• description (optional): Playlist description
• public (optional): Whether playlist is public (default: false)
• collaborative (optional): Whether playlist is collaborative (default: false)
• userId (optional): User ID to create playlist for (defaults to current user)

Returns: Created playlist details including Spotify URI and ID.

update_playlist_details

Update playlist metadata including name, description, privacy settings, and collaborative status.

Parameters:

• playlistId (required): Spotify playlist ID
• name (optional): New playlist name
• description (optional): New playlist description
• public (optional): New public/private setting
• collaborative (optional): New collaborative setting

Returns: Updated playlist details with change summary.

add_tracks_to_playlist

Add tracks to a playlist with precise position control.

Parameters:

• playlistId (required): Spotify playlist ID
• uris (required): Array of Spotify track URIs (max 100)
• position (optional): Position to insert tracks (defaults to end)

Returns: Confirmation with snapshot ID and updated track count.

remove_tracks_from_playlist

Remove tracks from a playlist with precision control.

Parameters:

• playlistId (required): Spotify playlist ID
• tracks (required): Array of track objects with URIs and optional positions
• snapshot_id (optional): Playlist snapshot ID for concurrency safety

Returns: Confirmation with snapshot ID and removal details.

reorder_playlist_tracks

Reorder tracks within a playlist by moving a range of tracks to a new position.

Parameters:

• playlistId (required): Spotify playlist ID
• range_start (required): Starting position of tracks to move
• range_length (required): Number of tracks to move
• insert_before (required): Position to move tracks to
• snapshot_id (optional): Playlist snapshot ID for concurrency safety

Returns: Confirmation with snapshot ID and reorder details.

🔍 Music Search & Discovery

search

Search Spotify's catalog for albums, artists, tracks, playlists, shows, and episodes.

Parameters:

• query (required): Search query string
• type (optional): Content type filter (track, album, artist, playlist, show, episode)
• limit (optional): Number of results (1-50, default: 20)
• offset (optional): Result offset (default: 0)
• market (optional): Country code for market-specific results

Returns: Detailed metadata for each result type with pagination information.

get_new_releases

Get new album releases available on Spotify.

Parameters:

• limit (optional): Number of releases (1-50, default: 20)
• offset (optional): Result offset (default: 0)
• country (optional): Country code for regional releases

Returns: Recently released albums with artist information, release dates, and metadata.

get_featured_playlists

Get featured playlists from Spotify's editorial team.

Parameters:

• limit (optional): Number of playlists (1-50, default: 20)
• offset (optional): Result offset (default: 0)
• country (optional): Country code for regional content
• locale (optional): Language/locale for descriptions

Returns: Curated playlists prominently featured on Spotify with descriptions and metadata.

👤 User Library & Insights

get_user_top_items

Get the current user's top artists or tracks based on calculated affinity.

Parameters:

• type (required): Item type ('artists' or 'tracks')
• time_range (optional): Time range ('short_term' ~4 weeks, 'medium_term' ~6 months, 'long_term' ~1 year)
• limit (optional): Number of items (1-50, default: 20)
• offset (optional): Result offset (default: 0)

Returns: User's top items with popularity scores and metadata.

🎧 Playback Control (Premium Only)

Note: These tools require a Spotify Premium account

get_current_playback

Get current playing track and device information.

Returns: Current playback state including track, device, and queue information.

playback_control

Control playback (play, pause, skip, volume).

Parameters:

• action (required): Playback action (play, pause, next, previous, volume)
• device_id (optional): Target device ID
• volume_percent (optional): Volume level (0-100, for volume action)

Returns: Confirmation of playback action.

queue_management

Add tracks to queue and view upcoming tracks.

Parameters:

• action (required): Queue action ('add' or 'get')
• uris (optional): Track URIs to add (for 'add' action)
• device_id (optional): Target device ID

Returns: Queue information or confirmation of track addition.

device_management

Transfer playback between devices.

Parameters:

• device_id (required): Target device ID
• play (optional): Whether to start playback on transfer (default: false)

Returns: Confirmation of device transfer.

📊 Audio Analysis

get_audio_features

Retrieve audio features for tracks.

Parameters:

• track_ids (required): Array of Spotify track IDs

Returns: Audio features including:

• Danceability: How suitable for dancing (0.0-1.0)
• Energy: Intensity and power (0.0-1.0)
• Speechiness: Presence of spoken words (0.0-1.0)
• Acousticness: Whether track is acoustic (0.0-1.0)
• Instrumentalness: Whether track has no vocals (0.0-1.0)
• Liveness: Presence of audience (0.0-1.0)
• Valence: Musical positivity/happiness (0.0-1.0)
• Tempo: Speed in beats per minute (BPM)

⚙️ Environment Variables

*These tokens are automatically obtained through the OAuth flow when you first use the server.

👥 User Roles

• developer: Full access to all tools and features
• editor: Restricted to content-focused tools (no admin features)

Set the role in your MCP client configuration if supported.

📦 Node.js Environment Setup

If you use a Node version manager (nvm, mise, fnm, etc.), you may need to create symlinks so MCP servers can access Node.js:

sudo ln -sf "$(which node)" /usr/local/bin/node && sudo ln -sf "$(which npx)" /usr/local/bin/npx

Update these symlinks if you change Node versions. Remove them with:

sudo rm /usr/local/bin/node /usr/local/bin/npx

💻 Development

Install dependencies:

npm install

Build and run in development mode:

npm run dev

Build the server:

npm run build

Run the built server:

npm start

🧑‍💻 Debugging

You can use the MCP inspector for debugging:

npx @modelcontextprotocol/inspector -e SPOTIFY_CLIENT_ID=... -e SPOTIFY_CLIENT_SECRET=... -e SPOTIFY_REDIRECT_URI=... -e SPOTIFY_API_TOKEN=... -e SPOTIFY_REFRESH_TOKEN=... node path/to/build/index.js

This provides a web interface for inspecting and testing the available tools.

OAuth Flow

The OAuth flow has been improved with the following security and usability enhancements:

Security Improvements

• State validation: Uses cryptographically secure random state parameters to prevent CSRF attacks
• Redirect URI validation: Ensures redirect URI uses localhost/127.0.0.1 for automatic token exchange
• Proper error handling: Comprehensive error handling for all OAuth failure scenarios

Usability Improvements

• Automatic browser opening: Automatically opens the authorization URL in your default browser
• Better user feedback: Clear error messages and status updates throughout the process
• Graceful server shutdown: Properly closes the OAuth callback server after completion

Using the OAuth Helper

The oauth-helper.js script provides a standalone way to obtain Spotify tokens:

node src/utils/oauth-helper.js

This will:

1. Validate your environment configuration
2. Start a local callback server
3. Automatically open your browser to the Spotify authorization page
4. Handle the callback and exchange the code for tokens
5. Display the tokens for you to add to your .env file

Environment Variables

Make sure your redirect URI is configured correctly:

SPOTIFY_REDIRECT_URI=http://127.0.0.1:8000/callback

The redirect URI must use localhost or 127.0.0.1 for the automatic token exchange to work properly.

License

MIT