# 🎵 Spotify MCP Server

A Model Context Protocol (MCP) server that integrates Spotify with Claude, enabling voice-controlled music playback, playlist management, and personalized music recommendations directly through conversational AI.

## ✨ Features

### 🎵 Playback Control
- Get currently playing track with full details
- Play specific tracks by name or ID
- Pause/resume playback
- Skip to next/previous tracks
- Adjust volume levels
- Toggle shuffle mode

### ❤️ Library Management
- Like/unlike songs
- Add tracks to Liked Songs
- Remove tracks from Liked Songs

### 📝 Playlist Operations
- Create new playlists
- Add tracks to existing playlists
- Search and discover music

### 🔍 Discovery & Search
- Search for tracks, artists, albums, and playlists
- Get personalized recommendations
- View top tracks and artists (customizable time ranges)

### 📊 Analytics
- View your most played tracks
- See your top artists
- Analyze listening habits over different time periods

## 🚀 Prerequisites

- Node.js v18 or higher
- Claude Desktop
- Spotify Premium account (required for playback control)
- Spotify Developer account

## 📦 Installation

### 1. Create Spotify Developer App

1. Go to [Spotify Developer Dashboard](https://developer.spotify.com/dashboard)
2. Log in with your Spotify account
3. Click **"Create app"**
4. Fill in:
   - **App name**: `Claude MCP Integration`
   - **App description**: `MCP server for Claude AI`
   - **Redirect URI**: `http://localhost:3000/callback` ⚠️ **CRITICAL**
5. Save and note your **Client ID** and **Client Secret**

### 2. Clone and Setup

```bash
# Clone the repository
git clone https://github.com/MadhurToshniwal/Spotify-MCP-Server.git
cd Spotify-MCP-Server

# Install dependencies
npm install

# Build the project
npm run build
```

### 3. Configure Environment Variables

Create a `.env` file in the project root:

```env
SPOTIFY_CLIENT_ID=your_client_id_here
SPOTIFY_CLIENT_SECRET=your_client_secret_here
SPOTIFY_REFRESH_TOKEN=will_get_this_next
```

### 4. Authorize Your Spotify Account

Run the OAuth helper script:

```bash
npm run auth
```

This will:
1. Start a local server on port 3000
2. Open your browser to Spotify's authorization page
3. After you authorize, display your **refresh token**
4. Copy the refresh token and add it to your `.env` file

### 5. Configure Claude Desktop

Edit your Claude Desktop configuration file:

**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`  
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

Add this configuration:

```json
{
  "mcpServers": {
    "spotify": {
      "command": "node",
      "args": [
        "/absolute/path/to/spotify-mcp-server/dist/index.js"
      ],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id",
        "SPOTIFY_CLIENT_SECRET": "your_client_secret",
        "SPOTIFY_REFRESH_TOKEN": "your_refresh_token"
      }
    }
  }
}
```

**Important for Windows users**: Use double backslashes in paths:
```json
"args": ["C:\\Users\\YourName\\Desktop\\spotify-mcp-server\\dist\\index.js"]
```

### 6. Restart Claude Desktop

Completely quit and restart Claude Desktop for changes to take effect.

## 🎮 Usage Examples

Once configured, you can ask Claude:

### Playback Control
- "What song am I listening to?"
- "Pause the music"
- "Play the next song"
- "Set volume to 70%"
- "Turn shuffle on"

### Search & Discovery
- "Search for songs by The Weeknd"
- "Find some jazz playlists"
- "Search for the album 'Abbey Road'"

### Library Management
- "Add this song to my liked songs"
- "Unlike this track"
- "Create a playlist called 'Workout Mix'"
- "Add these 3 songs to my playlist"

### Analytics
- "What are my top 10 songs this month?"
- "Show me my most played artists"
- "What have I been listening to recently?"

### Advanced
- "Search for 'Bohemian Rhapsody' and play it"
- "Create a playlist called 'Study Music' and add 5 calm songs"
- "Find electronic music playlists and play the most popular one"

## 🛠️ Available Tools

| Tool | Description |
|------|-------------|
| `search_music` | Search for tracks, artists, albums, or playlists |
| `get_current_track` | Get the currently playing track |
| `play_track` | Play a specific track by URI or ID |
| `pause_playback` | Pause current playback |
| `resume_playback` | Resume playback |
| `skip_to_next` | Skip to next track |
| `skip_to_previous` | Skip to previous track |
| `like_track` | Add track to Liked Songs |
| `unlike_track` | Remove track from Liked Songs |
| `create_playlist` | Create a new playlist |
| `add_to_playlist` | Add tracks to a playlist |
| `get_top_tracks` | Get your top tracks |
| `get_top_artists` | Get your top artists |
| `set_volume` | Set playback volume (0-100) |
| `toggle_shuffle` | Enable/disable shuffle |

## 🔒 Security Notes

- Never commit your `.env` file to version control
- Keep your Client Secret secure
- Refresh tokens are long-lived - store them safely
- The server uses OAuth 2.0 with automatic token refresh

## 📊 API Limits

Spotify Web API rate limits:
- Web API calls are rate-limited by Spotify
- Most endpoints allow several requests per second
- The server handles token refresh automatically

## 🐛 Troubleshooting

### "No active device found"
**Solution**: Open Spotify on your device and play any song to activate a device.

### "Invalid refresh token"
**Solution**: Run `npm run auth` again to get a new refresh token.

### Tools not appearing in Claude
**Solution**: 
1. Verify the path in `claude_desktop_config.json` is correct
2. Ensure all environment variables are set
3. Restart Claude Desktop completely

### "Premium required" errors
**Solution**: Some features (playback control) require Spotify Premium.

## 📁 Project Structure

```
spotify-mcp-server/
├── src/
│   ├── index.ts                # Main MCP server
│   └── get-refresh-token.ts    # OAuth helper script
├── dist/                       # Compiled JavaScript
├── .env                        # Environment variables (not in repo)
├── package.json
├── tsconfig.json
└── README.md
```

## 🚀 Development

```bash
# Build the project
npm run build

# Run the OAuth helper
npm run auth

# Run in development
npm start
```

## 🧪 Technologies Used

- **TypeScript**: Type-safe development
- **Model Context Protocol (MCP)**: Claude integration standard
- **Spotify Web API**: Music streaming service API
- **OAuth 2.0**: Secure authentication protocol
- **Express.js**: Web server for OAuth flow
- **Axios**: HTTP client for API requests

## 📜 License

MIT

## 👤 Author

**Madhur Toshniwal**

📧 Email: madhurtoshniwal03@gmail.com

## 🙏 Acknowledgments

- Spotify for their comprehensive Web API
- Anthropic for the Model Context Protocol
- Claude Desktop for AI integration

---

**Built to showcase API integration, OAuth implementation, and modern development practices for campus placement interviews.**

## 🎓 Learning Outcomes

This project demonstrates:
- OAuth 2.0 authentication flow implementation
- RESTful API integration and error handling
- Secure credential management
- Real-time data synchronization
- TypeScript for type-safe development
- MCP protocol implementation
- Asynchronous programming patterns