# Spotify MCP Server

Model Context Protocol (MCP) server that provides Spotify integration for Claude Desktop.

![experimental badge](https://img.shields.io/badge/status-experimental-orange)

> ⚠️ **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