Spotify MCP Server

# Spotify MCP Server Model Context Protocol (MCP) server that provides Spotify integration for Claude Desktop.  > ⚠️ **This project is experimental / for personal use only** > > This repository is a personal project created for fun and learning. It has not been exhaustively tested or production hardened. Use at your own risk — including re-authenticating if scopes change and backing up any important data. ## Features ### 🔍 Search - Search for tracks, albums, artists, and playlists ### 🎵 Playback Control - Get current playback state - Play/pause, skip, previous track - Control volume and shuffle - Seek within tracks ### 📚 Library Management - Get saved tracks - Save and remove tracks from library - Check if tracks are saved ### 🎼 Playlists - Get user playlists - Create new playlists - Add/remove tracks from playlists - Get playlist details ### 🎯 Recommendations - Get personalized recommendations based on: - Seed tracks, artists, or genres - Mood preferences (energy, danceability, valence) - Automatic recommendations from recent listening history - Get available genre seeds ### 💬 Intelligent Prompts - **Discover Music**: Get recommendations based on mood and preferences - **Analyze Now Playing**: Deep analysis of currently playing track - **Create Themed Playlist**: Build playlists around themes or activities ## Setup ### 1. Create Spotify App 1. Go to [Spotify Developer Dashboard](https://developer.spotify.com/dashboard) 2. Click "Create app" 3. Fill in: - App name: "MCP Spotify" (or any name) - App description: "Personal Spotify MCP Server" - Redirect URI: `http://localhost:3000/callback` 4. Check "Web API" under "Which API/SDKs are you planning to use?" 5. Agree to terms and click "Save" 6. Click "Settings" to view your **Client ID** and **Client Secret** ### 2. Configure Environment Create a `.env` file in the project root: ```env SPOTIFY_CLIENT_ID=your_client_id_here SPOTIFY_CLIENT_SECRET=your_client_secret_here SPOTIFY_REDIRECT_URI=http://localhost:3000/callback ``` ### 3. Build the Server ```bash npm install npm run build ``` ### 4. Configure Claude Desktop Edit your Claude Desktop config file: **Windows:** `%APPDATA%\Claude\claude_desktop_config.json` **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json` Add the MCP server configuration: ```json { "mcpServers": { "mcp-spotify": { "command": "node", "args": [ "C:\\path\\to\\mcp-spotify\\build\\index.js" ] } } } ``` Replace `C:\\path\\to\\mcp-spotify` with the actual path to this project. ### 5. First Run Authentication 1. Restart Claude Desktop 2. The server will automatically open a browser for Spotify authentication 3. Log in and authorize the app 4. You'll be redirected to a success page 5. Tokens are saved to `~/.mcp-spotify/tokens.json` ## Available Tools ### Search - `search_tracks` - Search for tracks - `search_albums` - Search for albums - `search_artists` - Search for artists - `search_playlists` - Search for playlists ### Playback - `get_playback_state` - Get current playback information - `playback_control` - Control playback (play, pause, skip, previous, shuffle, volume, seek) ### Library - `get_saved_tracks` - Get user's saved tracks - `save_tracks` - Save tracks to library - `remove_saved_tracks` - Remove tracks from library - `get_recently_played` - Get recently played tracks (useful for recommendations) ### Playlists - `get_playlists` - Get user's playlists - `create_playlist` - Create a new playlist - `add_tracks_to_playlist` - Add tracks to a playlist ### Recommendations - `get_recommendations` - Get track recommendations based on seeds and preferences (supports `use_recent_listening` parameter) - `get_genre_seeds` - Get list of available genre seeds ## Available Prompts ### `discover_music` Discover new music based on your mood, genres, and listening preferences. **Arguments:** - `mood` (optional): Desired mood (energetic, chill, happy, melancholic) - `genre` (optional): Preferred genre **Example:** "Discover energetic electronic music" ### `analyze_now_playing` Get detailed analysis of the currently playing track including audio features and recommendations. **Example:** "Analyze what I'm listening to" ### `create_themed_playlist` Create a playlist based on a theme, mood, or activity. **Arguments:** - `theme`: Theme or mood (e.g., "Workout", "Study", "Road Trip") - `size` (optional): Number of tracks (default: 20) **Example:** "Create a chill study playlist with 30 songs" ## Example Interactions ``` You: "What am I currently listening to?" → Uses get_playback_state to show current track You: "Find me some energetic electronic music" → Uses search_tracks or get_recommendations with appropriate filters You: "Create a workout playlist" → Uses create_themed_playlist prompt to search, gather tracks, and create playlist You: "Save this track to my library" → Uses save_tracks to add the current or mentioned track You: "Skip to the next song" → Uses playback_control with action: "skip" ``` ## Project Structure ``` src/ ├── index.ts # Main entry point, server setup ├── auth.ts # OAuth 2.0 authentication flow ├── spotify-client.ts # HTTP client for Spotify API ├── logger.ts # Logging utility ├── types.ts # TypeScript type definitions ├── utils.ts # Helper utilities ├── tools/ │ ├── search.ts # Search functionality │ ├── playback.ts # Playback control │ ├── library.ts # Library management │ ├── playlists.ts # Playlist operations │ ├── recommendations.ts # Recommendations logic │ └── declarations/ │ └── *.ts # Tool registration └── prompts/ └── declarations/ └── *.ts # Prompt registration ``` ## Troubleshooting ### "Spotify API error: 401" - Tokens may be expired. Delete `~/.mcp-spotify/tokens.json` and restart Claude - Check that your Client ID and Client Secret are correct in `.env` ### "No playback device found" - Open Spotify on any device (desktop, mobile, web) - Start playing any track to activate a device - The API requires an active device for playback control ### Recommendations returning 404 - This is expected! Spotify deprecated the old recommendations API - The server now uses Search API with filters as a replacement ## Technical Details - **Language:** TypeScript - **Runtime:** Node.js v23.9.0 - **MCP SDK:** @modelcontextprotocol/sdk v1.20.0 - **Transport:** stdio - **Auth:** OAuth 2.0 Authorization Code Flow with refresh tokens - **Token Storage:** `~/.mcp-spotify/tokens.json` (auto-refreshed) ## License MIT