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

Go to the Spotify Developer Dashboard
Create a new application
Note your Client ID and Client Secret
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

Call the get_initial_context tool in your AI application
If not already authorized, you'll receive an authorization URL
Open the URL in your browser and log in to Spotify
Authorize the application - you'll be redirected automatically
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

Variable	Description	Required
SPOTIFY_CLIENT_ID	Spotify client ID	✅
SPOTIFY_CLIENT_SECRET	Spotify client secret	✅
SPOTIFY_REDIRECT_URI	Spotify redirect URI (use http://127.0.0.1:8000/callback)	✅
SPOTIFY_API_TOKEN	Spotify access token (obtained via OAuth)	❌*
SPOTIFY_REFRESH_TOKEN	Spotify refresh token (obtained via OAuth)	❌*
MAX_TOOL_TOKEN_OUTPUT	Max token output for tool responses (default 50000)	❌

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

Validate your environment configuration
Start a local callback server
Automatically open your browser to the Spotify authorization page
Handle the callback and exchange the code for tokens
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

Name		Name	Last commit message	Last commit date
Latest commit History 9 Commits
scripts		scripts
src		src
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
eslint.config.js		eslint.config.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

License

tylerpina/spotify-mcp

Folders and files

Latest commit

History

Repository files navigation

Spotify MCP Server

✨ Key Features

🚀 Quickstart Guide

Prerequisites

Step 1: Get Spotify API Credentials

Step 2: Set Environment Variables

Step 3: Install and Run

Step 4: Connect from Your AI Tool

Step 5: Complete Authorization

🛠️ Available Tools

🔧 Context & Setup

get_initial_context

📝 Playlist Operations

get_user_playlists

create_playlist

update_playlist_details

add_tracks_to_playlist

remove_tracks_from_playlist

reorder_playlist_tracks

🔍 Music Search & Discovery

search

get_new_releases

get_featured_playlists

👤 User Library & Insights

get_user_top_items

🎧 Playback Control (Premium Only)

get_current_playback

playback_control

queue_management

device_management

📊 Audio Analysis

get_audio_features

⚙️ Environment Variables

👥 User Roles

📦 Node.js Environment Setup

💻 Development

🧑‍💻 Debugging

OAuth Flow

Security Improvements

Usability Improvements

Using the OAuth Helper

Environment Variables

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

`get_initial_context`

`get_user_playlists`

`create_playlist`

`update_playlist_details`

`add_tracks_to_playlist`

`remove_tracks_from_playlist`

`reorder_playlist_tracks`

`search`

`get_new_releases`

`get_featured_playlists`

`get_user_top_items`

`get_current_playback`

`playback_control`

`queue_management`

`device_management`

`get_audio_features`

Packages