Control Spotify and create custom playlists using the Spotify Web API through Claude Desktop.
Cross-platform support for Windows, macOS, and Linux.

Quick Start • Features • Installation • Tools • Documentation • Contributing

🎵 Turn Claude into your personal Spotify DJ!

Based on spotify-dxt by Kenneth Lien Rewritten for cross-platform compatibility using Spotify Web API

• 🤖 AI-Powered Control - Control Spotify using natural language through Claude Desktop
• 🎨 Smart Playlists - Create and curate playlists with AI assistance
• 🔍 Deep Analysis - Get detailed audio feature analysis and statistics
• ⚡ Easy Setup - Simple token generation script - no complex OAuth needed
• 🌍 Cross-Platform - Works on Windows, macOS, and Linux
• 🔌 22 Tools - Comprehensive Spotify control and management
• 📦 One-Click Install - MCPB bundle format for instant deployment

You: "What's playing on Spotify?"
Claude: Shows currently playing track with artist and album info

You: "Play some upbeat jazz music"
Claude: Searches for jazz tracks and starts playing them instantly

You: "Create a workout playlist with high-energy tracks"
Claude: Searches for energetic songs and creates a custom playlist

You: "Play my workout playlist"
Claude: Finds and plays your workout playlist immediately

You: "Analyze my Discover Weekly and tell me the vibe"
Claude: Provides audio feature analysis with energy, danceability, mood stats

You: "Skip to the next track and turn up the volume"
Claude: Controls playback instantly

The new Smart Play functionality makes controlling Spotify more intuitive than ever:

You: "Play"
Claude: Resumes your current playback instantly

You: "Play some chill indie rock"
Claude: Searches for indie rock tracks and starts playing the top results

You: "Play tracks by The Beatles"
Claude: Finds Beatles songs and starts a Beatles listening session

You: "Play my workout playlist"
Claude: Searches your playlists and plays your workout mix

You: "Play Discover Weekly"
Claude: Finds and plays your Discover Weekly automatically

You: Create a playlist called "Study Music"
Claude: Creates the playlist successfully
You: "Play Study Music"
Claude: Recognizes the recently created playlist and plays it immediately

The smart play functionality automatically detects what you want based on your query - no need to specify whether you want tracks or playlists!

1. Download the latest bundle from releases
2. Get credentials from Spotify Developer Dashboard
3. Generate token: Run npm run get-token in the project directory to get your refresh token
4. Install bundle: Double-click spotify-mcpb-0.2.4.mcpb and enter all three credentials
5. Start using: "What's playing on Spotify?" 🎵

⏱️ Setup time: ~5 minutes | See SETUP.md for detailed instructions

# Clone and install
git clone https://github.com/fabioc-aloha/spotify-mcpb.git
cd spotify-mcpb
npm install

# Configure credentials
cp .env.example .env
# Edit .env with your Spotify API credentials

# Run locally
npm start

# Build bundle (optional)
npm install -g @anthropic-ai/mcpb
mcpb pack . spotify-mcpb-0.2.4.mcpb

See BUNDLE.md for complete build instructions.

• Smart Play - Intelligent play function that can:
  • Resume playback (no parameters)
  • Play search results (with query: "play jazz music")
  • Play playlists by name ("play my workout playlist")
  • Context-aware playlist detection (remembers recently created playlists)
• Skip Tracks - Next/previous track navigation
• Volume Control - Set volume level (0-100)
• Playback Info - Get current track and full playback state

• Catalog Search - Search millions of tracks
• AI Recommendations - Get smart track suggestions based on:
  • Audio features (energy, danceability, tempo, mood)
  • Seed tracks, artists, or genres
  • Customizable targets and ranges

• Create Playlists - Build new playlists with custom names/descriptions
• Add Tracks - Smart track addition with automatic deduplication
• View Playlists - Get detailed playlist information
• List User Playlists - Browse all your playlists

• Liked Songs - Access and manage your saved tracks
• Save/Remove Tracks - Add or remove tracks from your library
• Library Status - Check if tracks are already saved
• Saved Albums - Browse and manage your saved albums

• Track Features - Get detailed audio characteristics:
  • Acousticness, danceability, energy, valence
  • Tempo, key, mode, time signature
  • Loudness, speechiness, instrumentalness
• Playlist Analytics - Comprehensive statistics:
  • Mean, standard deviation, min/max for all features
  • Total duration and track count
  • Diversity score (coefficient of variation)

• OAuth Flow - Built-in token generation (no manual scripts!)
• Secure Storage - Credentials managed via environment variables
• Auto Refresh - Automatic token renewal

0. spotify_get_refresh_token - Interactive OAuth flow (no manual scripts needed!)

1. spotify_play - Smart play function: Resume playback (no params), play search results (with query), or play playlist by name
2. spotify_play_playlist - Play a specific playlist by name or ID
3. spotify_pause - Pause playback
4. spotify_next_track - Skip to next track
5. spotify_previous_track - Skip to previous track
6. spotify_set_volume - Set volume (0-100)

7. spotify_get_current_track - Get currently playing track
8. spotify_get_playback_state - Get full playback state
9. spotify_search_tracks - Search Spotify catalog

10. spotify_create_playlist - Create new playlist
11. spotify_add_tracks_to_playlist - Add tracks with deduplication
12. spotify_get_playlist - Get playlist details
13. spotify_get_user_playlists - List user's playlists

14. spotify_get_saved_tracks - Get user's saved tracks (Liked Songs)
15. spotify_save_tracks - Save tracks to library (add to Liked Songs)
16. spotify_remove_saved_tracks - Remove tracks from library
17. spotify_check_saved_tracks - Check if tracks are saved in library
18. spotify_get_saved_albums - Get user's saved albums

19. spotify_get_recommendations - Get track recommendations
20. spotify_get_audio_features - Get audio features for tracks
21. spotify_analyze_playlist - Analyze playlist statistics

Contributions are welcome! Here's how you can help:

• 🐛 Report Bugs: Open an issue
• 💡 Suggest Features: Share your ideas in issues
• 📖 Improve Documentation: Submit PRs for docs
• 🔧 Submit Code: Fork, create a branch, and submit a PR

• Bundle Size: 3.0 MB (compressed)
• Total Files: 1,767+ files
• Dependencies: 60 production packages
• Code Quality: 0 vulnerabilities
• MCP Tools: 22 comprehensive tools
• API Compliance: 100% (verified October 2025)

• spotify-dxt - Original macOS-only version by Kenneth Lien
• MCP SDK - Model Context Protocol SDK
• Claude Desktop - AI assistant with MCP support
• MCPB Spec - MCP Bundle specification

• Kenneth Lien - Original spotify-dxt project
• Anthropic - MCPB specification and Claude Desktop
• Spotify - Web API and developer platform
• MCP Community - Model Context Protocol ecosystem

MIT License - See LICENSE.md

TL;DR: Free to use, modify, and distribute. Just keep the license notice.

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Spotify API: Developer Documentation
• MCP Protocol: Official Docs

If you find this project useful, please consider:

• ⭐ Starring the repository
• 🐦 Sharing on social media
• 🔗 Linking from your projects
• 🤝 Contributing improvements

Made with ❤️ by Fabio Correa
_{Based on the original macOS-only spotify-dxt, reimagined for cross-platform use}

Download Latest Release →