MCP Spotify AI Assistant
A Model Context Protocol (MCP) server that enables Claude to control Spotify features.
Contents
Example Interactions
- "Can you add the top 5 Coldplay songs to my playlist vibes"
- "What are my most listened to songs this past month"
- "Can you shuffle play my top songs"
Tools
Read Operations
-
searchSpotify
- Description: Search for tracks, albums, artists, or playlists on Spotify
- Parameters:
query(string): The search termtype(string): Type of item to search for (track, album, artist, playlist)limit(number, optional): Maximum number of results to return (10-50)
- Returns: List of matching items with their IDs, names, and additional details
- Example:
searchSpotify("bohemian rhapsody", "track", 20)
-
getTopItems
- Description: Get the current user's top artists or tracks based on calculated affinity
- Parameters:
type(string): The type of entity to return. Valid values: artists or trackstime_range(string, optional): Over what time frame the affinities are computed. Long_term ~1 year of data, medium_term is last 6 months, short_term is last 4 weekslimit(number, optional): The maximum number of items to return. Default: 20, minimum: 1, maximum: 50
- Returns: List of matching items with name, ids, and additional details
- Example:
getTopItems("artists", "short_term", 5)
-
getMyPlaylists
- Description: Get a list of the playlists owned or followed by the current Spotify user
- Parameters:
limit(number, optional): The maximum number of items to return. Default: 20, minimum: 1, maximum: 50
- Returns: List of matching playlists with name, ids, and additional details
- Example:
getMyPlaylists(25)
-
getPlaylistItems
- Description: Get full details of the items of a playlist owned by a Spotify user
- Parameters:
playlist_id(string): The Spotify ID of the playlistfields(string, optional): A comma-separated list of the fields to returnlimit(number, optional): The maximum number of items to return. Default: 20, minimum: 1, maximum: 50
- Returns: List of matching playlist items with name, ids, and additional details
- Example:
getPlaylistItems("123")
-
getCurrentUserProfile
- Description: Get detailed profile information about the current user
- Parameters: None
- Returns: Users' display name, id, email, and number of followers
- Example:
getCurrentUserProfile()
-
getCurrentlyPlaying
- Description: Get full details of the items of a playlist owned by a Spotify user
- Parameters: None
- Returns: Returns the currently playing item's name and accompanying details
- Example:
getCurrentlyPlaying()
-
getRecentlyPlayedTracks
- Description: Get full details of the items of a playlist owned by a Spotify user
- Parameters:
limit(number, optional): The maximum number of items to return. Default: 20, minimum: 1, maximum: 50
- Returns: List recently played tracks' names and additional information
- Example:
getRecentlyPlayedTracks(20)
-
getUserQueue
- Description: Get the list of objects that make up the user's queue
- Parameters: None
- Returns: The items' names and additional information in the queue
- Example:
getUserQueue()
Write Operations
-
startPlayback
- Description: Start a new playback on the active device
- Parameters:
device_id(string, optional): The ID of the device this command is targetingcontext_uri(number, optional): Spotify URI of the context to play. Valid contexts are albums, artists, and playliststype(number, optional): The type to play. Valid types are track, album, artist, or playlistid(number, optional): The Spotify ID of the item to play
- Returns: Playback started
- Example:
startPlayback()
-
resumePlayback
- Description: Resume playback on the active device
- Parameters:
device_id(string, optional): The ID of the device this command is targeting
- Returns: Playback resumed
- Example:
resumePlayback()
-
pausePlayback
- Description: Pause playback on the active device
- Parameters:
device_id(string, optional): The ID of the device this command is targeting
- Returns: Playback paused
- Example:
pausePlayback()
-
addQueue
- Description: Add an item to be played next in the playback queue
- Parameters:
uri(string): The URI of the item to add to the queue. Must be a track or an episode URIdevice_id(string, optional): The ID of the device this command is targeting
- Returns: Added to Queue
- Example:
addQueue("123uri")
-
togglePlaybackShuffle
- Description: Toggle shuffle on or off for the user's playback
- Parameters:
state(boolean): True: Shuffle the user's playback. False: Do not shuffle the user's playbackdevice_id(string, optional): The ID of the device this command is targeting
- Returns: Shuffle changed
- Example:
togglePlaybackShuffle(true)
-
createPlaylist
- Description: Create a playlist for a Spotify user
- Parameters:
device_id(string): The user's Spotify user IDname(string): The name for your new playlistpublic(boolean, optional): The playlist's public/private statusdescription(string, optional): The playlist's description
- Returns: New playlist created
- Example:
createPlaylist("user123", "new playlist", true, "This is a new playlist")
-
addItemsToPlaylist
- Description: Adds one or more items to a user's playlist
- Parameters:
playlist_id(string): The Spotify ID of the playlisturis(string, optional): A comma-separated list of Spotify URIs to add, can be track or episode URIstypes(boolean, optional): A comma-separated list of types in the same order as idsids(string, optional): A comma-separated list of ids in the same order as types
- Returns: Items added to playlist
- Example:
createPlaylist("playlist123")
-
changePlaylistDetails
- Description: Change a playlist's name and public/private state
- Parameters:
playlist_id(string): The Spotify ID of the playlistname(string, optional): The new name for the playlistpublic(boolean, optional): The playlist's new public/private statusdescription(string, optional): Value for playlist description
- Returns: Playlist details changed
- Example:
changePlaylistDetails("playlist123", "new new playlist")
Setup
Prerequisites
- Node.js v16+
- A Spotify Premium account
- A registered Spotify Developer application
Installation
git clone https://github.com/iankan04/MCP-Spotify.git
cd mcp-spotify
npm install
npm run build
Creating a Spotify Developer Application
- Go to the Spotify Developer Dashboard
- Log in with your Spotify account
- Click the "Create an App" button
- Fill in the app name and description
- Accept the Terms of Service and click "Create"
- In your new app's dashboard, you'll see your Client ID
- Click "Show Client Secret" to reveal your Client Secret
- Click "Edit Settings" and add a Redirect URI (e.g.,
http://localhost:8000/callback) - Save your changes
Spotify API Configuration
Create a .env.local file in the project root (you can copy and modify the provided example):
SPOTIFY_CLIENT_ID='Your client_id'
SPOTIFY_CLIENT_SECRET='Your client_secret'
SPOTIFY_REDIRECT_URI='Your redirect_uri (i.e. http://127.0.0.1:8000/callback'
Make sure your redirect_uri follows the newest Spotify Developer Settings.
Authentication Process
The Spotify API uses OAuth 2.0 for authentication. Follow these steps to authenticate your application:
- Open two terminal screens. In one, run
redis-server
In the other, run
npm run auth
-
The script will generate an authorization URL. Open this URL in your web browser.
-
You'll be prompted to log in to Spotify and authorize your application.
-
After authorization, Spotify will redirect you to your specified redirect URI with a code parameter in the URL.
-
The authentication script will automatically exchange this code for access and refresh tokens.
-
These tokens will be saved to the Redis database and automatically refreshed when called
Integrating with Claude Desktop
To use your MCP server with Claude Desktop, add it to your Claude configuration:
{
"mcpServers": {
"spotify": {
"command": "node",
"args": ["MCP-Spotify/build/index.js"]
}
}
}
If Claude is running, restart the application, and you should see "spotify" as a new tool