Skip to content
Back to search

spotify-mcp-server

Lightweight MCP server for Spotify

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/marcelmarais/spotify-mcp-server with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/marcelmarais/spotify-mcp-server'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/marcelmarais--spotify-mcp-server/badge.svg)](/listings/marcelmarais--spotify-mcp-server)

HTML

<a href="/listings/marcelmarais--spotify-mcp-server"><img src="/api/listings/marcelmarais--spotify-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

- Latest Node.js Current release (currently v26.8.1; older release lines are unsupported) - A Spotify Premium account - A registered Spotify Developer application

Installation

git clone https://github.com/marcelmarais/spotify-mcp-server.git
cd spotify-mcp-server
npm ci
npm run build

Creating a Spotify Developer Application

1. Go to the [Spotify Developer Dashboard](https://developer.spotify.com/dashboard/) 2. Log in with your Spotify account 3. Click the "Create an App" button 4. Fill in the app name and description 5. Accept the Terms of Service and click "Create" 6. In your new app's dashboard, you'll see your **Client ID** 7. Click "Show Client Secret" to reveal your **Client Secret** 8. Click "Edit Settings" and add a Redirect URI (e.g., `http://127.0.0.1:8888/callback`) 9. Save your changes

Spotify API Configuration

Create a `spotify-config.json` file in the project root (you can copy and modify the provided example):

# Copy the example config file
cp spotify-config.example.json spotify-config.json

Then edit the file with your credentials:

{
  "clientId": "your-client-id",
  "clientSecret": "your-client-secret",
  "redirectUri": "http://127.0.0.1:8888/callback"
}

Authentication Process

The Spotify API uses OAuth 2.0 for authentication. Follow these steps to authenticate your application:

1. Run the authentication script:

npm run auth

2. The script will generate an authorization URL. Open this URL in your web browser.

3. You'll be prompted to log in to Spotify and authorize your application.

4. After authorization, Spotify will redirect you to your specified redirect URI with a code parameter in the URL.

5. The authentication script will automatically exchange this code for access and refresh tokens.

6. These tokens will be saved to your `spotify-config.json` file, which will now look something like:

{
  "clientId": "your-client-id",
  "clientSecret": "your-client-secret",
  "redirectUri": "http://localhost:8888/callback",
  "accessToken": "BQAi9Pn...kKQ",
  "refreshToken": "AQDQcj...7w",
  "expiresAt": 1677889354671
}

**Note**: The `expiresAt` field is a Unix timestamp (in milliseconds) indicating when the access token expires.

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 632 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  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. A lightweight [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that enables AI assistants like Cursor & Claude to control Spotify playback and manage playlists.
  6. Built by Marcel Marais · [Differentiated](https://differentiated.io) · [LinkedIn](https://www.linkedin.com/in/marcelmarais1/) · [X](https://x.com/marcelmarais)
  7. <details>
  8. <summary>Contents</summary>
  9. - [Example Interactions](#example-interactions)
  10. - [Tools](#tools)
  11. - [Read Operations](#read-operations)
  12. - [Album Operations](#album-operations)
  13. - [Play / Create Operations](#play--create-operations)
  14. - [Playlist Operations](#playlist-operations)
  15. - [Setup](#setup)
  16. - [Prerequisites](#prerequisites)
  17. - [Installation](#installation)
  18. - [Creating a Spotify Developer Application](#creating-a-spotify-developer-application)
  19. - [Spotify API Configuration](#spotify-api-configuration)
  20. - [Authentication Process](#authentication-process)
  21. - [Integrating with Claude Desktop, Cursor, and VsCode (Cline)](#integrating-with-claude-desktop-and-cursor)
  22. - [Streamable HTTP](#streamable-http)
  23. - [OAuth (MCPHub and other OAuth-capable clients)](#oauth-mcphub-and-other-oauth-capable-clients)
  24. - [Docker (recommended for MCPHub)](#docker-recommended-for-mcphub)
  25. </details>
  26. ## Example Interactions
  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. ## Tools
  32. ### Read Operations
  33. 1. **searchSpotify**
  34. - **Description**: Search for tracks, albums, artists, or playlists on Spotify
  35. - **Parameters**:
  36. - `query` (string): The search term
  37. - `type` (string): Type of item to search for (track, album, artist, playlist)
  38. - `limit` (number, optional): Maximum number of results to return (1-10, default: 10)
  39. - `offset` (number, optional): Index of the first result to return (default: 0)
  40. - **Returns**: List of matching items with their IDs, names, and additional details
  41. - **Example**: `searchSpotify("bohemian rhapsody", "track", 10)`
  42. 2. **getNowPlaying**
  43. - **Description**: Get information about the currently playing track on Spotify, including device and volume info
  44. - **Parameters**: None
  45. - **Returns**: Object containing track name, artist, album, playback progress, duration, playback state, device info, volume, and shuffle/repeat status
  46. - **Example**: `getNowPlaying()`
  47. 3. **getMyPlaylists**
  48. - **Description**: Get a list of the current user's playlists on Spotify
  49. - **Parameters**:
  50. - `limit` (number, optional): Maximum number of playlists to return (default: 20)
  51. - `offset` (number, optional): Index of the first playlist to return (default: 0)
  52. - **Returns**: Array of playlists with their IDs, names, track counts, and public status
  53. - **Example**: `getMyPlaylists(10, 0)`
  54. 4. **getPlaylistTracks**
  55. - **Description**: Get a list of tracks in a specific Spotify playlist
  56. - **Parameters**:
  57. - `playlistId` (string): The Spotify ID of the playlist
  58. - `limit` (number, optional): Maximum number of tracks to return (default: 100)
  59. - `offset` (number, optional): Index of the first track to return (default: 0)
  60. - **Returns**: Array of tracks with their IDs, names, artists, album, duration, and added date
  61. - **Example**: `getPlaylistTracks("37i9dQZEVXcJZyENOWUFo7")`
  62. 5. **getRecentlyPlayed**
  63. - **Description**: Retrieves a list of recently played tracks from Spotify.
  64. - **Parameters**:
  65. - `limit` (number, optional): A number specifying the maximum number of tracks to return.
  66. - **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".
  67. - **Example**: `getRecentlyPlayed({ limit: 10 })`
  68. 6. **getUsersSavedTracks**
  69. - **Description**: Get a list of tracks saved in the user's "Liked Songs" library
  70. - **Parameters**:
  71. - `limit` (number, optional): Maximum number of tracks to return (1-50, default: 50)
  72. - `offset` (number, optional): Offset for pagination (0-based index, default: 0)
  73. - **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").
  74. - **Example**: `getUsersSavedTracks({ limit: 20, offset: 0 })`
  75. 7. **getQueue**
  76. - **Description**: Get the currently playing track and upcoming items in the Spotify queue
  77. - **Parameters**:
  78. - `limit` (number, optional): Maximum number of upcoming items to show (1-50, default: 10)
  79. - **Returns**: Currently playing track and list of upcoming tracks in the queue
  80. - **Example**: `getQueue({ limit: 20 })`
  81. 8. **getAvailableDevices**
  82. - **Description**: Get information about the user's available Spotify Connect devices
  83. - **Parameters**: None
  84. - **Returns**: List of available devices with name, type, active status, volume, and device ID
  85. - **Example**: `getAvailableDevices()`
  86. 9. **removeUsersSavedTracks**
  87. - **Description**: Remove one or more tracks from the user's "Liked Songs" library (max 40 per request)
  88. - **Parameters**:
  89. - `trackIds` (array): Array of Spotify track IDs to remove (max 40)
  90. - **Returns**: Success confirmation message
  91. - **Example**: `removeUsersSavedTracks({ trackIds: ["4iV5W9uYEdYUVa79Axb7Rh", "1301WleyT98MSxVHPZCA6M"] })`
  92. 10. **getFollowedArtists**
  93. - **Description**: Get the artists the current user follows
  94. - **Parameters**:
  95. - `limit` (number, optional): Maximum number of artists to return (1-50, default: 20)
  96. - `after` (string, optional): Cursor from a previous call (the last artist ID) to fetch the next page
  97. - **Returns**: Formatted list of followed artists with names and IDs (plus popularity and genres when Spotify provides them), and a cursor for the next page when more remain
  98. - **Example**: `getFollowedArtists({ limit: 50 })`
  99. ### Play / Create Operations
  100. 1. **playMusic**
  101. - **Description**: Start playing a track, album, artist, or playlist on Spotify
  102. - **Parameters**:
  103. - `uri` (string, optional): Spotify URI of the item to play (overrides type and id)
  104. - `type` (string, optional): Type of item to play (track, album, artist, playlist)
  105. - `id` (string, optional): Spotify ID of the item to play
  106. - `deviceId` (string, optional): ID of the device to play on
  107. - **Returns**: Success status
  108. - **Example**: `playMusic({ uri: "spotify:track:6rqhFgbbKwnb9MLmUQDhG6" })`
  109. - **Alternative**: `playMusic({ type: "track", id: "6rqhFgbbKwnb9MLmUQDhG6" })`
  110. 2. **pausePlayback**
  111. - **Description**: Pause the currently playing track on Spotify
  112. - **Parameters**:
  113. - `deviceId` (string, optional): ID of the device to pause
  114. - **Returns**: Success status
  115. - **Example**: `pausePlayback()`
  116. 3. **resumePlayback**
  117. - **Description**: Resume Spotify playback on the active device
  118. - **Parameters**:
  119. - `deviceId` (string, optional): ID of the device to resume playback on
  120. - **Returns**: Success status
  121. - **Example**: `resumePlayback()`
  122. 4. **skipToNext**
  123. - **Description**: Skip to the next track in the current playback queue
  124. - **Parameters**:
  125. - `deviceId` (string, optional): ID of the device
  126. - **Returns**: Success status
  127. - **Example**: `skipToNext()`
  128. 5. **skipToPrevious**
  129. - **Description**: Skip to the previous track in the current playback queue
  130. - **Parameters**:
  131. - `deviceId` (string, optional): ID of the device
  132. - **Returns**: Success status
  133. - **Example**: `skipToPrevious()`
  134. 6. **createPlaylist**
  135. - **Description**: Create a new playlist on Spotify
  136. - **Parameters**:
  137. - `name` (string): Name for the new playlist
  138. - `description` (string, optional): Description for the playlist
  139. - `public` (boolean, optional): Whether the playlist should be public (default: false)
  140. - **Returns**: Object with the new playlist's ID and URL
  141. - **Example**: `createPlaylist({ name: "Workout Mix", description: "Songs to get pumped up", public: false })`
  142. 7. **addTracksToPlaylist**
  143. - **Description**: Add tracks to an existing Spotify playlist
  144. - **Parameters**:
  145. - `playlistId` (string): ID of the playlist
  146. - `trackUris` (array): Array of track URIs or IDs to add
  147. - `position` (number, optional): Position to insert tracks
  148. - **Returns**: Success status and snapshot ID
  149. - **Example**: `addTracksToPlaylist({ playlistId: "3cEYpjA9oz9GiPac4AsH4n", trackUris: ["spotify:track:4iV5W9uYEdYUVa79Axb7Rh"] })`
  150. 8. **addToQueue**
  151. - **Description**: Adds items to the end of the playback queue, in order, without interrupting playback. Queues a list of tracks/episodes in one call, or expands an album or playlist into its tracks (Spotify's queue only accepts tracks and episodes, so artists aren't supported). Queues at most 100 items per call.
  152. - **Parameters**:
  153. - `trackIds` (array, optional): Spotify IDs or URIs to queue in order (max 100). Plain IDs are treated as tracks; use `spotify:episode:{id}` for episodes
  154. - `uri` (string, optional): Spotify URI of a single track, episode, album or playlist (overrides type and id)
  155. - `type` (string, optional): Type of item to queue (track, episode, album, playlist)
  156. - `id` (string, optional): Spotify ID of the item to queue
  157. - `offset` (number, optional): Album/playlist only: index of the first track to queue (default: 0)
  158. - `limit` (number, optional): Album/playlist only: maximum number of tracks to queue (default and max: 100)
  159. - `deviceId` (string, optional): ID of the device to queue on
  160. - **Returns**: How many items were queued, any removed or local tracks that were skipped, and the offset to continue from if the album or playlist has more. If Spotify fails partway through, it reports how many were queued and which item it stopped at
  161. - **Example**: `addToQueue({ trackIds: ["6rqhFgbbKwnb9MLmUQDhG6", "4iV5W9uYEdYUVa79Axb7Rh"] })`
  162. - **Alternative**: `addToQueue({ uri: "spotify:playlist:3cEYpjA9oz9GiPac4AsH4n", limit: 20 })`
  163. 9. **setVolume**
  164. - **Description**: Set the playback volume to a specific percentage (requires Spotify Premium)
  165. - **Parameters**:
  166. - `volumePercent` (number): The volume to set (0-100)
  167. - `deviceId` (string, optional): ID of the device to set volume on
  168. - **Returns**: Success status with the new volume level
  169. - **Example**: `setVolume({ volumePercent: 50 })`
  170. 10. **adjustVolume**
  171. - **Description**: Adjust the playback volume up or down by a relative amount (requires Spotify Premium)
  172. - **Parameters**:
  173. - `adjustment` (number): The amount to adjust volume by (-100 to 100). Positive values increase volume, negative values decrease it.
  174. - `deviceId` (string, optional): ID of the device to adjust volume on
  175. - **Returns**: Success status showing the volume change (e.g., "Volume increased from 50% to 60%")
  176. - **Example**: `adjustVolume({ adjustment: 10 })` (increase by 10%)
  177. - **Example**: `adjustVolume({ adjustment: -20 })` (decrease by 20%)
  178. ### Album Operations
  179. 1. **getAlbums**
  180. - **Description**: Get detailed information about one or more albums by their Spotify IDs
  181. - **Parameters**:
  182. - `albumIds` (string|array): A single album ID or array of album IDs (max 20)
  183. - **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.
  184. - **Example**: `getAlbums("4aawyAB9vmqN3uQ7FjRGTy")` or `getAlbums(["4aawyAB9vmqN3uQ7FjRGTy", "1DFixLWuPkv3KT3TnV35m3"])`
  185. 2. **getAlbumTracks**
  186. - **Description**: Get tracks from a specific album with pagination support
  187. - **Parameters**:
  188. - `albumId` (string): The Spotify ID of the album
  189. - `limit` (number, optional): Maximum number of tracks to return (1-50)
  190. - `offset` (number, optional): Offset for pagination (0-based index)
  191. - **Returns**: List of tracks from the album with track names, artists, duration, and IDs. Shows pagination info.
  192. - **Example**: `getAlbumTracks("4aawyAB9vmqN3uQ7FjRGTy", 10, 0)`
  193. 3. **saveOrRemoveAlbumForUser**
  194. - **Description**: Save or remove albums from the user's "Your Music" library
  195. - **Parameters**:
  196. - `albumIds` (array): Array of Spotify album IDs (max 20)
  197. - `action` (string): Action to perform: "save" or "remove"
  198. - **Returns**: Success status with confirmation message
  199. - **Example**: `saveOrRemoveAlbumForUser(["4aawyAB9vmqN3uQ7FjRGTy"], "save")`
  200. 4. **checkUsersSavedAlbums**
  201. - **Description**: Check if albums are saved in the user's "Your Music" library
  202. - **Parameters**:
  203. - `albumIds` (array): Array of Spotify album IDs to check (max 20)
  204. - **Returns**: Status of each album (saved or not saved)
  205. - **Example**: `checkUsersSavedAlbums(["4aawyAB9vmqN3uQ7FjRGTy", "1DFixLWuPkv3KT3TnV35m3"])`
  206. ### Playlist Operations
  207. 1. **getPlaylist**
  208. - **Description**: Get details of a specific Spotify playlist including tracks count, description and owner
  209. - **Parameters**:
  210. - `playlistId` (string): The Spotify ID of the playlist
  211. - **Returns**: Playlist name, owner, track count, visibility, description, ID, and URL
  212. - **Example**: `getPlaylist({ playlistId: "37i9dQZEVXcJZyENOWUFo7" })`
  213. 2. **updatePlaylist**
  214. - **Description**: Update the details of a Spotify playlist (name, description, public/private, collaborative)
  215. - **Parameters**:
  216. - `playlistId` (string): The Spotify ID of the playlist
  217. - `name` (string, optional): New name for the playlist
  218. - `description` (string, optional): New description for the playlist
  219. - `public` (boolean, optional): Whether the playlist should be public
  220. - `collaborative` (boolean, optional): Whether the playlist should be collaborative (requires public to be false)
  221. - **Returns**: Success confirmation with list of updated fields
  222. - **Example**: `updatePlaylist({ playlistId: "3cEYpjA9oz9GiPac4AsH4n", name: "New Name", public: true })`
  223. 3. **removeTracksFromPlaylist**
  224. - **Description**: Remove one or more tracks from a Spotify playlist (max 100 tracks per request)
  225. - **Parameters**:
  226. - `playlistId` (string): The Spotify ID of the playlist
  227. - `trackIds` (array): Array of Spotify track IDs to remove (max 100)
  228. - `snapshotId` (string, optional): The playlist snapshot ID to target a specific version
  229. - **Returns**: Success confirmation with the number of tracks removed
  230. - **Example**: `removeTracksFromPlaylist({ playlistId: "3cEYpjA9oz9GiPac4AsH4n", trackIds: ["4iV5W9uYEdYUVa79Axb7Rh"] })`
  231. 4. **reorderPlaylistItems**
  232. - **Description**: Reorder a range of tracks within a Spotify playlist by moving them to a new position
  233. - **Parameters**:
  234. - `playlistId` (string): The Spotify ID of the playlist
  235. - `rangeStart` (number): The position of the first item to move (0-based index)
  236. - `insertBefore` (number): The position where the items should be inserted (0-based index)
  237. - `rangeLength` (number, optional): Number of consecutive items to move (defaults to 1)
  238. - `snapshotId` (string, optional): The playlist snapshot ID to target a specific version
  239. - **Returns**: Success confirmation with the move details
  240. - **Example**: `reorderPlaylistItems({ playlistId: "3cEYpjA9oz9GiPac4AsH4n", rangeStart: 2, insertBefore: 0 })`
  241. ## Setup
  242. ### Prerequisites
  243. - Latest Node.js Current release (currently v26.8.1; older release lines are unsupported)
  244. - A Spotify Premium account
  245. - A registered Spotify Developer application
  246. ### Installation
  247. ```bash
  248. git clone https://github.com/marcelmarais/spotify-mcp-server.git
  249. cd spotify-mcp-server
  250. npm ci
  251. npm run build
  252. ```
  253. ### Creating a Spotify Developer Application
  254. 1. Go to the [Spotify Developer Dashboard](https://developer.spotify.com/dashboard/)
  255. 2. Log in with your Spotify account
  256. 3. Click the "Create an App" button
  257. 4. Fill in the app name and description
  258. 5. Accept the Terms of Service and click "Create"
  259. 6. In your new app's dashboard, you'll see your **Client ID**
  260. 7. Click "Show Client Secret" to reveal your **Client Secret**
  261. 8. Click "Edit Settings" and add a Redirect URI (e.g., `http://127.0.0.1:8888/callback`)
  262. 9. Save your changes
  263. ### Spotify API Configuration
  264. Create a `spotify-config.json` file in the project root (you can copy and modify the provided example):
  265. ```bash
  266. # Copy the example config file
  267. cp spotify-config.example.json spotify-config.json
  268. ```
  269. Then edit the file with your credentials:
  270. ```json
  271. {
  272. "clientId": "your-client-id",
  273. "clientSecret": "your-client-secret",
  274. "redirectUri": "http://127.0.0.1:8888/callback"
  275. }
  276. ```
  277. ### Authentication Process
  278. The Spotify API uses OAuth 2.0 for authentication. Follow these steps to authenticate your application:
  279. 1. Run the authentication script:
  280. ```bash
  281. npm run auth
  282. ```
  283. 2. The script will generate an authorization URL. Open this URL in your web browser.
  284. 3. You'll be prompted to log in to Spotify and authorize your application.
  285. 4. After authorization, Spotify will redirect you to your specified redirect URI with a code parameter in the URL.
  286. 5. The authentication script will automatically exchange this code for access and refresh tokens.
  287. 6. These tokens will be saved to your `spotify-config.json` file, which will now look something like:
  288. ```json
  289. {
  290. "clientId": "your-client-id",
  291. "clientSecret": "your-client-secret",
  292. "redirectUri": "http://localhost:8888/callback",
  293. "accessToken": "BQAi9Pn...kKQ",
  294. "refreshToken": "AQDQcj...7w",
  295. "expiresAt": 1677889354671
  296. }
  297. ```
  298. **Note**: The `expiresAt` field is a Unix timestamp (in milliseconds) indicating when the access token expires.
  299. 7. **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.
  300. ## Integrating with Claude Desktop, Cursor, and VsCode [Via Cline model extension](https://marketplace.visualstudio.com/items/?itemName=saoudrizwan.claude-dev)
  301. To use your MCP server with Claude Desktop, add it to your Claude configuration:
  302. ```json
  303. {
  304. "mcpServers": {
  305. "spotify": {
  306. "command": "node",
  307. "args": ["spotify-mcp-server/build/index.js"]
  308. }
  309. }
  310. }
  311. ```
  312. For Cursor, go to the MCP tab in `Cursor Settings` (command + shift + J). Add a server with this command:
  313. ```bash
  314. node path/to/spotify-mcp-server/build/index.js
  315. ```
  316. To set up your MCP correctly with Cline ensure you have the following file configuration set `cline_mcp_settings.json`:
  317. ```json
  318. {
  319. "mcpServers": {
  320. "spotify": {
  321. "command": "node",
  322. "args": ["~/../spotify-mcp-server/build/index.js"],
  323. "autoApprove": ["getListeningHistory", "getNowPlaying"]
  324. }
  325. }
  326. }
  327. ```
  328. You can add additional tools to the auto approval array to run the tools without intervention.
  329. ### Streamable HTTP
  330. The server uses stdio by default. To run one long-lived process that several MCP clients connect to over HTTP instead, set `MCP_TRANSPORT=http`:
  331. ```bash
  332. MCP_TRANSPORT=http MCP_HTTP_PORT=3000 node path/to/spotify-mcp-server/build/index.js
  333. ```
  334. Clients then connect to `http://127.0.0.1:3000/mcp`. `MCP_HTTP_PORT` defaults to `3000` and `MCP_HTTP_HOST` to `127.0.0.1`. On a loopback address, requests whose `Host` or `Origin` header names anything other than `localhost`, `127.0.0.1`, `[::1]`, `MCP_HTTP_HOST` or the bound address are rejected to prevent DNS rebinding. The endpoint has no authentication, so only bind another address behind something that provides it.
  335. ### OAuth (MCPHub and other OAuth-capable clients)
  336. Set `MCP_AUTH=spotify` in addition to `MCP_TRANSPORT=http`. The server then acts as an OAuth-protected MCP endpoint (RFC 9728) whose authorization server is Spotify itself:
  337. ```bash
  338. MCP_TRANSPORT=http MCP_HTTP_PORT=3000 MCP_AUTH=spotify node path/to/spotify-mcp-server/build/index.js
  339. ```
  340. - `POST /mcp` without an `Authorization: Bearer` header returns `401` with a `WWW-Authenticate` challenge pointing at `/.well-known/oauth-protected-resource`.
  341. - That metadata document advertises `https://accounts.spotify.com` as the authorization server (plus the full required scope set under `scopes_supported`), so clients with OAuth support (e.g. MCPHub) discover Spotify, run the authorization-code flow in the browser, and reconnect with the issued access token.
  342. - The Bearer token is used **per request** as the Spotify access token and is never written to `spotify-config.json` — no `npm run auth`, no stored refresh token, no token-refresh timer. Token rotation by the client is handled transparently.
  343. - On the first request of each new token (i.e. on rotation) the server validates it against Spotify (`GET /me`) and memoises the result. If Spotify rejects the token the server answers `401` with `WWW-Authenticate: Bearer error="invalid_token"`, so the client knows to reauthorise. A token is **not trusted forever**: if Spotify later 401s a tool call with an already-validated token (expiry or revocation), the server evicts it from the validation memo, and the next request re-runs the `/me` ping instead of reusing the stale result. Spotify issues opaque tokens (no JWKS, no public introspection endpoint), so the `/me` ping is the strongest validation possible without the client secret — it proves the token works with Spotify, but cannot verify the token was issued for *this* app (that would require the client secret, which this mode deliberately does not hold).
  344. - `spotify-config.json` is not required in this mode. stdio mode is unchanged and still uses the config file.
  345. Environment variables:
  346. | Variable | Default | Purpose |
  347. | --- | --- | --- |
  348. | `MCP_AUTH` | unset (stdio/config-file mode) | `spotify` enables Bearer-token auth on the HTTP transport |
  349. | `SPOTIFY_RESOURCE_URL` | derived from bind host/port | `resource` value in the protected-resource metadata. Set this to the public URL the MCP client uses when the server is reachable under a different address (reverse proxy, Docker port mapping). |
  350. | `SPOTIFY_AUTHORIZATION_SERVERS` | `https://accounts.spotify.com` | Comma-separated list of authorization server URLs in the metadata. |
  351. **One-time Spotify app setup** (same dashboard as for the other flows): add the redirect URI your MCP client uses for callbacks (e.g. `http://127.0.0.1:3000/oauth/callback` for a local MCPHub dashboard — Spotify rejects `localhost` redirect URIs for new apps, so use `127.0.0.1` or an HTTPS URL) and copy the **client ID** into the client's OAuth configuration. Spotify does not support dynamic client registration, so the client ID must be provided manually. The client secret is only needed by clients that exchange the code using `client_secret_basic`/`client_secret_post`.
  352. Request the **full scope set** advertised in the metadata's `scopes_supported` (15 scopes); if a client requests fewer, tools that need the missing scopes fail with `403`.
  353. Example MCPHub configuration:
  354. ```json
  355. {
  356. "mcpServers": {
  357. "spotify": {
  358. "type": "streamable-http",
  359. "url": "http://127.0.0.1:3000/mcp",
  360. "oauth": {
  361. "clientId": "your-spotify-client-id",
  362. "authorizationEndpoint": "https://accounts.spotify.com/authorize",
  363. "tokenEndpoint": "https://accounts.spotify.com/api/token",
  364. "redirectUri": "http://127.0.0.1:3000/oauth/callback",
  365. "scopes": [
  366. "user-read-private",
  367. "user-read-email",
  368. "user-read-playback-state",
  369. "user-modify-playback-state",
  370. "user-read-currently-playing",
  371. "user-read-playback-position",
  372. "playlist-read-private",
  373. "playlist-read-collaborative",
  374. "playlist-modify-private",
  375. "playlist-modify-public",
  376. "user-library-read",
  377. "user-library-modify",
  378. "user-read-recently-played",
  379. "user-top-read",
  380. "user-follow-read"
  381. ],
  382. "resource": "http://127.0.0.1:3000"
  383. }
  384. }
  385. }
  386. }
  387. ```
  388. ### Docker (recommended for MCPHub)
  389. The repository ships a `Dockerfile` (multi-stage, `node:26-alpine`, unprivileged
  390. user) and a `docker-compose.yml` that run the server in **OAuth-protected
  391. Streamable HTTP mode** on an internal Docker network. No host port is published,
  392. so the server is not exposed on the host's external interfaces — only your
  393. MCPHub container (on the same Docker network) can reach it at
  394. `http://spotify-mcp:3000/mcp`. Only the MCPHub dashboard/callback URL needs to
  395. be publicly reachable, because Spotify's `redirect_uri` points at MCPHub.
  396. The image needs **no client secret, no refresh token and no `spotify-config.json`**.
  397. 1. Build and start the server:
  398. ```bash
  399. docker compose up -d --build
  400. ```
  401. 2. In the Spotify Developer Dashboard, add the **MCPHub callback URL** as a
  402. redirect URI for your app (e.g. `http://127.0.0.1:3000/oauth/callback` for a
  403. local MCPHub — Spotify rejects `localhost` redirect URIs for new apps — or
  404. your deployed MCPHub dashboard domain) and copy the **client ID**.
  405. 3. Connect MCPHub to the server. Point `url` at the Docker DNS name and set
  406. `resource` to the same value (this must match `SPOTIFY_RESOURCE_URL`, which
  407. the server advertises in its protected-resource metadata):
  408. ```json
  409. {
  410. "mcpServers": {
  411. "spotify": {
  412. "type": "streamable-http",
  413. "url": "http://spotify-mcp:3000/mcp",
  414. "oauth": {
  415. "clientId": "your-spotify-client-id",
  416. "authorizationEndpoint": "https://accounts.spotify.com/authorize",
  417. "tokenEndpoint": "https://accounts.spotify.com/api/token",
  418. "redirectUri": "http://127.0.0.1:3000/oauth/callback",
  419. "scopes": [
  420. "user-read-private",
  421. "user-read-email",
  422. "user-read-playback-state",
  423. "user-modify-playback-state",
  424. "user-read-currently-playing",
  425. "user-read-playback-position",
  426. "playlist-read-private",
  427. "playlist-read-collaborative",
  428. "playlist-modify-private",
  429. "playlist-modify-public",
  430. "user-library-read",
  431. "user-library-modify",
  432. "user-read-recently-played",
  433. "user-top-read",
  434. "user-follow-read"
  435. ],
  436. "resource": "http://spotify-mcp:3000"
  437. }
  438. }
  439. }
  440. }
  441. ```
  442. The two `spotify-mcp` containers must share a Docker network. If MCPHub
  443. already runs in its own compose stack, join them: add the network to the
  444. MCPHub service **and** declare the shared network `external: true` in
  445. **both** compose files.
  446. MCPHub service (`mcphub` compose file):
  447. ```yaml
  448. services:
  449. mcphub:
  450. networks:
  451. - mcphub # its own network (from its existing file)
  452. - spotify-mcp # join the Spotify MCP network
  453. networks:
  454. spotify-mcp:
  455. external: true # the network is created by the other stack
  456. ```
  457. Or, if you manage both yourself, create the network once with
  458. `docker network create spotify-mcp` and mark it `external: true` in
  459. **both** compose files — including this one's `spotify-mcp` network
  460. definition — so neither stack tries to create it.
  461. 4. In MCPHub, the first call triggers the Spotify authorization flow in the
  462. browser; MCPHub stores the tokens and rotates them automatically.
  463. If MCPHub reaches the server through a different address (another host, a
  464. reverse proxy), set `SPOTIFY_RESOURCE_URL` in `.env` to that URL and mirror it
  465. in MCPHub's `oauth.resource`.
  466. #### Container images
  467. The **CI** workflow builds `linux/amd64` and `linux/arm64` images after lint,
  468. type checks and tests pass. Pull requests only build; pushes to the default
  469. branch and manual runs on that branch publish to
  470. `ghcr.io/<repository-owner>/<repository-name>` (lowercase), using `latest` and
  471. `sha-<full-commit-SHA>` tags. Pin an image digest for immutable deployments.
  472. Publishing uses the automatic `GITHUB_TOKEN` with `packages: write`; no personal
  473. access token is required. Enable Actions in new forks if prompted. After the
  474. first publication, make the package public in **Package settings → Change
  475. visibility** to allow anonymous pulls. New GHCR packages are private by default
  476. ([GitHub documentation](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry)).
  477. The image includes the upstream MIT license at `/app/LICENSE`.
  478. ## Development
  479. The server uses MCP TypeScript SDK v2 and Zod 4, serving protocol revision `2026-07-28` while retaining compatibility with legacy MCP clients. Only the latest Node.js Current release is supported (minimum v26.8.1). CI follows the latest Current release. Install the locked dependencies with `npm ci`.
  480. ```bash
  481. npm run lint
  482. npm run typecheck
  483. npm test
  484. ```
  485. Tests exercise MCP initialization, tool discovery, validation, and Spotify operations using mocked HTTP responses. They do not require Spotify credentials or change your Spotify account.
  486. ## License
  487. Licensed under the [MIT License](LICENSE).
  488. ### More tools by me
  489. - **[Stream](https://differentiated.io/stream)**: Daily notes for engineers, with your commits, pull requests, and agents in one place. Free for Mac.
  490. - **[Timeline](https://timeline.differentiated.io)**: Your location history for Claude, ChatGPT, and Cursor. Free for iPhone.
  491. Find all my tools and writing on AI engineering at **[Differentiated](https://differentiated.io/tools)**.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.