Spotify MCP Server

1<div align="center" style="display: flex; align-items: center; justify-content: center; gap: 10px;">
2<img src="https://upload.wikimedia.org/wikipedia/commons/8/84/Spotify_icon.svg" width="30" height="30">
3<h1>Spotify MCP Server</h1>
4</div>
5 
6A lightweight [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that enables AI assistants like Cursor & Claude to control Spotify playback and manage playlists.
7 
8<details>
9<summary>Contents</summary>
10 
11- [Example Interactions](#example-interactions)
12- [Tools](#tools)
13  - [Read Operations](#read-operations)
14  - [Album Operations](#album-operations)
15  - [Play / Create Operations](#play--create-operations)
16- [Setup](#setup)
17  - [Prerequisites](#prerequisites)
18  - [Installation](#installation)
19  - [Creating a Spotify Developer Application](#creating-a-spotify-developer-application)
20  - [Spotify API Configuration](#spotify-api-configuration)
21  - [Authentication Process](#authentication-process)
22- [Integrating with Claude Desktop, Cursor, and VsCode (Cline)](#integrating-with-claude-desktop-and-cursor)
23</details>
24 
25## Example Interactions
26 
27- _"Play Elvis's first song"_
28- _"Create a Taylor Swift / Slipknot fusion playlist"_
29- _"Copy all the techno tracks from my workout playlist to my work playlist"_
30- _"Turn the volume down a bit"_
31 
32## Tools
33 
34### Read Operations
35 
361. **searchSpotify**
37 
38   - **Description**: Search for tracks, albums, artists, or playlists on Spotify
39   - **Parameters**:
40     - `query` (string): The search term
41     - `type` (string): Type of item to search for (track, album, artist, playlist)
42     - `limit` (number, optional): Maximum number of results to return (10-50)
43   - **Returns**: List of matching items with their IDs, names, and additional details
44   - **Example**: `searchSpotify("bohemian rhapsody", "track", 20)`
45 
462. **getNowPlaying**
47 
48   - **Description**: Get information about the currently playing track on Spotify, including device and volume info
49   - **Parameters**: None
50   - **Returns**: Object containing track name, artist, album, playback progress, duration, playback state, device info, volume, and shuffle/repeat status
51   - **Example**: `getNowPlaying()`
52 
533. **getMyPlaylists**
54 
55   - **Description**: Get a list of the current user's playlists on Spotify
56   - **Parameters**:
57     - `limit` (number, optional): Maximum number of playlists to return (default: 20)
58     - `offset` (number, optional): Index of the first playlist to return (default: 0)
59   - **Returns**: Array of playlists with their IDs, names, track counts, and public status
60   - **Example**: `getMyPlaylists(10, 0)`
61 
624. **getPlaylistTracks**
63 
64   - **Description**: Get a list of tracks in a specific Spotify playlist
65   - **Parameters**:
66     - `playlistId` (string): The Spotify ID of the playlist
67     - `limit` (number, optional): Maximum number of tracks to return (default: 100)
68     - `offset` (number, optional): Index of the first track to return (default: 0)
69   - **Returns**: Array of tracks with their IDs, names, artists, album, duration, and added date
70   - **Example**: `getPlaylistTracks("37i9dQZEVXcJZyENOWUFo7")`
71 
725. **getRecentlyPlayed**
73 
74   - **Description**: Retrieves a list of recently played tracks from Spotify.
75   - **Parameters**:
76     - `limit` (number, optional): A number specifying the maximum number of tracks to return.
77   - **Returns**: If tracks are found it returns a formatted list of recently played tracks else a message stating: "You don't have any recently played tracks on Spotify".
78   - **Example**: `getRecentlyPlayed({ limit: 10 })`
79 
806. **getUsersSavedTracks**
81 
82   - **Description**: Get a list of tracks saved in the user's "Liked Songs" library
83   - **Parameters**:
84     - `limit` (number, optional): Maximum number of tracks to return (1-50, default: 50)
85     - `offset` (number, optional): Offset for pagination (0-based index, default: 0)
86   - **Returns**: Formatted list of saved tracks with track names, artists, duration, track IDs, and when they were added to Liked Songs. Shows pagination info (e.g., "1-20 of 150").
87   - **Example**: `getUsersSavedTracks({ limit: 20, offset: 0 })`
88 
897. **getQueue**
90 
91   - **Description**: Get the currently playing track and upcoming items in the Spotify queue
92   - **Parameters**:
93     - `limit` (number, optional): Maximum number of upcoming items to show (1-50, default: 10)
94   - **Returns**: Currently playing track and list of upcoming tracks in the queue
95   - **Example**: `getQueue({ limit: 20 })`
96 
978. **getAvailableDevices**
98 
99   - **Description**: Get information about the user's available Spotify Connect devices
100   - **Parameters**: None
101   - **Returns**: List of available devices with name, type, active status, volume, and device ID
102   - **Example**: `getAvailableDevices()`
103 
104 
105### Play / Create Operations
106 
1071. **playMusic**
108 
109   - **Description**: Start playing a track, album, artist, or playlist on Spotify
110   - **Parameters**:
111     - `uri` (string, optional): Spotify URI of the item to play (overrides type and id)
112     - `type` (string, optional): Type of item to play (track, album, artist, playlist)
113     - `id` (string, optional): Spotify ID of the item to play
114     - `deviceId` (string, optional): ID of the device to play on
115   - **Returns**: Success status
116   - **Example**: `playMusic({ uri: "spotify:track:6rqhFgbbKwnb9MLmUQDhG6" })`
117   - **Alternative**: `playMusic({ type: "track", id: "6rqhFgbbKwnb9MLmUQDhG6" })`
118 
1192. **pausePlayback**
120 
121   - **Description**: Pause the currently playing track on Spotify
122   - **Parameters**:
123     - `deviceId` (string, optional): ID of the device to pause
124   - **Returns**: Success status
125   - **Example**: `pausePlayback()`
126 
1273. **resumePlayback**
128 
129   - **Description**: Resume Spotify playback on the active device
130   - **Parameters**:
131     - `deviceId` (string, optional): ID of the device to resume playback on
132   - **Returns**: Success status
133   - **Example**: `resumePlayback()`
134 
1354. **skipToNext**
136 
137   - **Description**: Skip to the next track in the current playback queue
138   - **Parameters**:
139     - `deviceId` (string, optional): ID of the device
140   - **Returns**: Success status
141   - **Example**: `skipToNext()`
142 
1435. **skipToPrevious**
144 
145   - **Description**: Skip to the previous track in the current playback queue
146   - **Parameters**:
147     - `deviceId` (string, optional): ID of the device
148   - **Returns**: Success status
149   - **Example**: `skipToPrevious()`
150 
1516. **createPlaylist**
152 
153   - **Description**: Create a new playlist on Spotify
154   - **Parameters**:
155     - `name` (string): Name for the new playlist
156     - `description` (string, optional): Description for the playlist
157     - `public` (boolean, optional): Whether the playlist should be public (default: false)
158   - **Returns**: Object with the new playlist's ID and URL
159   - **Example**: `createPlaylist({ name: "Workout Mix", description: "Songs to get pumped up", public: false })`
160 
1617. **addTracksToPlaylist**
162 
163   - **Description**: Add tracks to an existing Spotify playlist
164   - **Parameters**:
165     - `playlistId` (string): ID of the playlist
166     - `trackUris` (array): Array of track URIs or IDs to add
167     - `position` (number, optional): Position to insert tracks
168   - **Returns**: Success status and snapshot ID
169   - **Example**: `addTracksToPlaylist({ playlistId: "3cEYpjA9oz9GiPac4AsH4n", trackUris: ["spotify:track:4iV5W9uYEdYUVa79Axb7Rh"] })`
170 
1718. **addToQueue**
172 
173   - **Description**: Adds a track, album, artist or playlist to the current playback queue
174   - **Parameters**:
175     - `uri` (string, optional): Spotify URI of the item to add to queue (overrides type and id)
176     - `type` (string, optional): Type of item to queue (track, album, artist, playlist)
177     - `id` (string, optional): Spotify ID of the item to queue
178     - `deviceId` (string, optional): ID of the device to queue on
179   - **Returns**: Success status
180   - **Example**: `addToQueue({ uri: "spotify:track:6rqhFgbbKwnb9MLmUQDhG6" })`
181   - **Alternative**: `addToQueue({ type: "track", id: "6rqhFgbbKwnb9MLmUQDhG6" })`
182 
1839. **setVolume**
184 
185   - **Description**: Set the playback volume to a specific percentage (requires Spotify Premium)
186   - **Parameters**:
187     - `volumePercent` (number): The volume to set (0-100)
188     - `deviceId` (string, optional): ID of the device to set volume on
189   - **Returns**: Success status with the new volume level
190   - **Example**: `setVolume({ volumePercent: 50 })`
191 
19210. **adjustVolume**
193 
194   - **Description**: Adjust the playback volume up or down by a relative amount (requires Spotify Premium)
195   - **Parameters**:
196     - `adjustment` (number): The amount to adjust volume by (-100 to 100). Positive values increase volume, negative values decrease it.
197     - `deviceId` (string, optional): ID of the device to adjust volume on
198   - **Returns**: Success status showing the volume change (e.g., "Volume increased from 50% to 60%")
199   - **Example**: `adjustVolume({ adjustment: 10 })` (increase by 10%)
200   - **Example**: `adjustVolume({ adjustment: -20 })` (decrease by 20%)
201 
202 
203### Album Operations
204 
2051. **getAlbums**
206 
207   - **Description**: Get detailed information about one or more albums by their Spotify IDs
208   - **Parameters**:
209     - `albumIds` (string|array): A single album ID or array of album IDs (max 20)
210   - **Returns**: Album details including name, artists, release date, type, total tracks, and ID. For single album returns detailed view, for multiple albums returns summary list.
211   - **Example**: `getAlbums("4aawyAB9vmqN3uQ7FjRGTy")` or `getAlbums(["4aawyAB9vmqN3uQ7FjRGTy", "1DFixLWuPkv3KT3TnV35m3"])`
212 
2132. **getAlbumTracks**
214 
215   - **Description**: Get tracks from a specific album with pagination support
216   - **Parameters**:
217     - `albumId` (string): The Spotify ID of the album
218     - `limit` (number, optional): Maximum number of tracks to return (1-50)
219     - `offset` (number, optional): Offset for pagination (0-based index)
220   - **Returns**: List of tracks from the album with track names, artists, duration, and IDs. Shows pagination info.
221   - **Example**: `getAlbumTracks("4aawyAB9vmqN3uQ7FjRGTy", 10, 0)`
222 
2233. **saveOrRemoveAlbumForUser**
224 
225   - **Description**: Save or remove albums from the user's "Your Music" library
226   - **Parameters**:
227     - `albumIds` (array): Array of Spotify album IDs (max 20)
228     - `action` (string): Action to perform: "save" or "remove"
229   - **Returns**: Success status with confirmation message
230   - **Example**: `saveOrRemoveAlbumForUser(["4aawyAB9vmqN3uQ7FjRGTy"], "save")`
231 
2324. **checkUsersSavedAlbums**
233 
234   - **Description**: Check if albums are saved in the user's "Your Music" library
235   - **Parameters**:
236     - `albumIds` (array): Array of Spotify album IDs to check (max 20)
237   - **Returns**: Status of each album (saved or not saved)
238   - **Example**: `checkUsersSavedAlbums(["4aawyAB9vmqN3uQ7FjRGTy", "1DFixLWuPkv3KT3TnV35m3"])`
239 
240## Setup
241 
242### Prerequisites
243 
244- Node.js v16+
245- A Spotify Premium account
246- A registered Spotify Developer application
247 
248### Installation
249 
250```bash
251git clone https://github.com/marcelmarais/spotify-mcp-server.git
252cd spotify-mcp-server
253npm install
254npm run build
255```
256 
257### Creating a Spotify Developer Application
258 
2591. Go to the [Spotify Developer Dashboard](https://developer.spotify.com/dashboard/)
2602. Log in with your Spotify account
2613. Click the "Create an App" button
2624. Fill in the app name and description
2635. Accept the Terms of Service and click "Create"
2646. In your new app's dashboard, you'll see your **Client ID**
2657. Click "Show Client Secret" to reveal your **Client Secret**
2668. Click "Edit Settings" and add a Redirect URI (e.g., `http://127.0.0.1:8888/callback`)
2679. Save your changes
268 
269### Spotify API Configuration
270 
271Create a `spotify-config.json` file in the project root (you can copy and modify the provided example):
272 
273```bash
274# Copy the example config file
275cp spotify-config.example.json spotify-config.json
276```
277 
278Then edit the file with your credentials:
279 
280```json
281{
282  "clientId": "your-client-id",
283  "clientSecret": "your-client-secret",
284  "redirectUri": "http://127.0.0.1:8888/callback"
285}
286```
287 
288### Authentication Process
289 
290The Spotify API uses OAuth 2.0 for authentication. Follow these steps to authenticate your application:
291 
2921. Run the authentication script:
293 
294```bash
295npm run auth
296```
297 
2982. The script will generate an authorization URL. Open this URL in your web browser.
299 
3003. You'll be prompted to log in to Spotify and authorize your application.
301 
3024. After authorization, Spotify will redirect you to your specified redirect URI with a code parameter in the URL.
303 
3045. The authentication script will automatically exchange this code for access and refresh tokens.
305 
3066. These tokens will be saved to your `spotify-config.json` file, which will now look something like:
307 
308```json
309{
310  "clientId": "your-client-id",
311  "clientSecret": "your-client-secret",
312  "redirectUri": "http://localhost:8888/callback",
313  "accessToken": "BQAi9Pn...kKQ",
314  "refreshToken": "AQDQcj...7w",
315  "expiresAt": 1677889354671
316}
317```
318 
319**Note**: The `expiresAt` field is a Unix timestamp (in milliseconds) indicating when the access token expires.
320 
3217. **Automatic Token Refresh**: The server will automatically refresh the access token when it expires (typically after 1 hour). The refresh happens transparently using the `refreshToken`, so you don't need to re-authenticate manually. If the refresh fails, you'll need to run `npm run auth` again to re-authenticate.
322 
323## Integrating with Claude Desktop, Cursor, and VsCode [Via Cline model extension](https://marketplace.visualstudio.com/items/?itemName=saoudrizwan.claude-dev)
324 
325To use your MCP server with Claude Desktop, add it to your Claude configuration:
326 
327```json
328{
329  "mcpServers": {
330    "spotify": {
331      "command": "node",
332      "args": ["spotify-mcp-server/build/index.js"]
333    }
334  }
335}
336```
337 
338For Cursor, go to the MCP tab in `Cursor Settings` (command + shift + J). Add a server with this command:
339 
340```bash
341node path/to/spotify-mcp-server/build/index.js
342```
343 
344To set up your MCP correctly with Cline ensure you have the following file configuration set `cline_mcp_settings.json`:
345 
346```json
347{
348  "mcpServers": {
349    "spotify": {
350      "command": "node",
351      "args": ["~/../spotify-mcp-server/build/index.js"],
352      "autoApprove": ["getListeningHistory", "getNowPlaying"]
353    }
354  }
355}
356```
357 
358You can add additional tools to the auto approval array to run the tools without intervention.
359