🎵 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
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

# 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:

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:

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:

{
  "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:

"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

# 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