sespinosa/spotify-mcp
If you are the rightful owner of spotify-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
A Model Context Protocol (MCP) server that provides tools for interacting with the Spotify Web API.
spotify_auth_url
Generate OAuth authorization URL
spotify_exchange_code
Exchange authorization code for tokens
spotify_set_tokens
Manually set access tokens
spotify_refresh_token
Refresh the access token
spotify_search
Search for content on Spotify
spotify_get_track
Get track details
spotify_get_artist
Get artist details
spotify_get_album
Get album details
spotify_get_playlist
Get playlist details
spotify_play
Start or resume playback
spotify_pause
Pause playback
spotify_next
Skip to next track
spotify_previous
Skip to previous track
spotify_seek
Seek to position in track
spotify_set_volume
Set playback volume
spotify_get_playback_state
Get current playback state
spotify_get_devices
Get available devices
spotify_transfer_playback
Transfer playback to another device
spotify_toggle_shuffle
Toggle shuffle mode
spotify_set_repeat
Set repeat mode
Spotify MCP Server
A Model Context Protocol (MCP) server that provides tools for interacting with the Spotify Web API.
Features
- Authentication: OAuth 2.0 with PKCE support
- Search: Search for tracks, artists, albums, and playlists
- Playback Control: Play, pause, skip, seek, volume control, and more
- Content Retrieval: Get detailed information about tracks, artists, albums, and playlists
Setup
-
Clone this repository
-
Install dependencies:
npm install
-
Create a Spotify App:
- Go to https://developer.spotify.com/dashboard
- Create a new app
- Add
http://127.0.0.1:8888/callback
to the Redirect URIs (orhttp://localhost:8888/callback
) - Copy your Client ID and Client Secret
-
Set up environment variables:
cp .env.example .env
Edit
.env
and add your Spotify credentials:SPOTIFY_CLIENT_ID=your_client_id_here SPOTIFY_CLIENT_SECRET=your_client_secret_here SPOTIFY_REDIRECT_URI=http://127.0.0.1:8888/callback SPOTIFY_PERSIST_TOKENS=false
-
Build the project:
npm run build
Usage
Running the Server
npm start
For development with auto-reload:
npm run dev
Available Tools
Authentication Tools
spotify_auth_url
: Generate OAuth authorization URLspotify_exchange_code
: Exchange authorization code for tokensspotify_set_tokens
: Manually set access tokensspotify_refresh_token
: Refresh the access token
Search Tools
spotify_search
: Search for content on Spotify- Parameters: query, type (track/artist/album/playlist), limit
Content Tools
spotify_get_track
: Get track detailsspotify_get_artist
: Get artist detailsspotify_get_album
: Get album detailsspotify_get_playlist
: Get playlist details
Playback Control Tools
spotify_play
: Start or resume playbackspotify_pause
: Pause playbackspotify_next
: Skip to next trackspotify_previous
: Skip to previous trackspotify_seek
: Seek to position in trackspotify_set_volume
: Set playback volumespotify_get_playback_state
: Get current playback statespotify_get_devices
: Get available devicesspotify_transfer_playback
: Transfer playback to another devicespotify_toggle_shuffle
: Toggle shuffle modespotify_set_repeat
: Set repeat mode (track/context/off)
Authentication Flow
- Use
spotify_auth_url
to generate an authorization URL with desired scopes - Direct user to the URL to authorize the app
- After authorization, use
spotify_exchange_code
with the code and state from the callback - The server will automatically manage token refresh when needed
Important for WSL Users: The callback URL (http://127.0.0.1:8888/callback
) won't automatically open in WSL. After authorizing in your browser, you'll be redirected to a URL that may not load. Copy the entire URL from your browser's address bar and paste it back to the LLM to complete the authentication process.
Token Persistence
By default, authentication tokens are stored only in memory and will be lost when the server restarts. To enable persistent token storage:
- Set the environment variable
SPOTIFY_PERSIST_TOKENS=true
- Tokens will be securely stored in your home directory (
~/.spotify-mcp-tokens.json
) - The server will automatically load saved tokens on startup
- Tokens are saved with proper file permissions (readable only by the owner)
Security Note: Tokens are stored in plaintext in your home directory. Only enable persistence if you trust the security of your system.
Example Usage with Claude Desktop
Add the server to your Claude Desktop configuration:
{
"mcpServers": {
"spotify": {
"command": "node",
"args": ["/path/to/spotify-mcp/dist/index.js"],
"env": {
"SPOTIFY_CLIENT_ID": "your_client_id",
"SPOTIFY_CLIENT_SECRET": "your_client_secret",
"SPOTIFY_REDIRECT_URI": "http://127.0.0.1:8888/callback",
"SPOTIFY_PERSIST_TOKENS": "false"
}
}
}
}
Configuration with Claude CLI
When using Claude CLI, configure the MCP server with the built JavaScript file:
claude mcp add spotify node /path/to/spotify-mcp/dist/index.js
Important: Make sure to use the compiled JavaScript file from the dist/
directory, not the TypeScript source. The server requires Node.js to run and will automatically load environment variables from the .env
file in the project root.
Required Scopes
Different features require different OAuth scopes:
- Basic search and content retrieval: No user scopes needed (uses Client Credentials)
- Playback control:
user-modify-playback-state
,user-read-playback-state
- User profile:
user-read-private
,user-read-email
- Library access:
user-library-read
,user-library-modify
- Playlist management:
playlist-read-private
,playlist-modify-public
,playlist-modify-private
Development
Project Structure
spotify-mcp/
āāā src/
ā āāā index.ts # Main server implementation
ā āāā auth.ts # OAuth authentication logic
ā āāā playback-tools.ts # Playback control tools
āāā dist/ # Compiled JavaScript
āāā package.json
āāā tsconfig.json
āāā README.md
Building
npm run build
Testing
The server uses stdio transport for communication with MCP clients. You can test it using any MCP-compatible client.
License
ISC