🎵 Spotify AI Playlist Generator
An intelligent MCP (Model Context Protocol) server that generates personalized Spotify playlists using AI. This project combines the power of Google's Gemini AI with Spotify's extensive music catalog to create curated playlists based on natural language prompts.
✨ Features
- AI-Powered Curation: Uses Google Gemini to generate intelligent search queries and curate track selections
- Spotify Integration: Full integration with Spotify's API for authentication, search, and playlist creation
- Personalized Recommendations: Analyzes user's listening history for better recommendations
- Natural Language Processing: Create playlists using simple prompts like "upbeat workout music" or "chill sunday morning vibes"
- Flexible Duration: Specify playlist length from 1 to 300 minutes
- MCP Server: Runs as a Model Context Protocol server for easy integration with AI assistants
- Health Monitoring: Built-in health checks and logging
🚀 Quick Start
Prerequisites
- Python 3.8+
- Spotify Premium account (recommended)
- Spotify Developer App credentials
- Google Gemini API key
Installation
-
Clone the repository
git clone <your-repo-url> cd spotify-playlist-generator -
Install dependencies
pip install -r requirements.txt -
Set up environment variables
cp .env.example .env # Edit .env with your credentials -
Run the server
python main.py
The server will start on http://127.0.0.1:10000 by default.
🔧 Configuration
Environment Variables
Create a .env file in the project root with the following variables:
# Spotify API Credentials
SPOTIFY_CLIENT_ID=your_spotify_client_id
SPOTIFY_CLIENT_SECRET=your_spotify_client_secret
# Google Gemini API Key
GEMINI_API_KEY=your_gemini_api_key
# Server Configuration
PORT=10000
# Optional: Your phone number for validation
MY_NUMBER=+1234567890
Spotify Developer Setup
- Go to Spotify Developer Dashboard
- Create a new app
- Note your Client ID and Client Secret
- Add redirect URI:
http://127.0.0.1:10000/callback - Add the required scopes (handled automatically by the app)
Google Gemini API Setup
- Go to Google AI Studio
- Create a new API key
- Add the key to your
.envfile
📖 Usage
1. Health Check
curl http://127.0.0.1:10000/health
2. Authenticate with Spotify
The server will provide an authentication URL. Visit it to authorize the application.
3. Fetch User Data
After authentication, fetch your Spotify listening history for personalized recommendations.
4. Generate Playlists
Create playlists using natural language prompts:
- "Energetic workout music for 45 minutes"
- "Chill indie songs for studying"
- "90s rock hits for a road trip"
- "Emotional ballads for a rainy day"
🛠️ API Endpoints
MCP Tools
The server exposes the following MCP tools:
health: Check server health statusvalidate: Validate configurationauthenticate: Get Spotify authentication URLfetch_data: Fetch and store user's Spotify datagenerate_playlist: Generate AI-curated playlist
Generate Playlist Parameters
{
"prompt": "string (required) - Description of desired playlist",
"duration_minutes": "integer (optional, default: 60) - Playlist length",
"playlist_name": "string (optional, default: 'AI Generated Playlist') - Playlist name"
}
🏗️ Architecture
Components
- Main Server (
main.py): FastMCP server handling HTTP requests and routing - Spotify Handler (
spotify_handler.py): Spotify API integration using Tekore - Playlist Generator (
playlist_generator.py): AI-powered playlist curation using Gemini
Data Flow
- User provides natural language prompt
- Gemini AI generates relevant search queries
- Spotify API searches for matching tracks
- System fetches additional recommendations based on user history
- Gemini AI curates the final track selection
- Spotify playlist is created and populated
File Structure
├── main.py # MCP server and main entry point
├── spotify_handler.py # Spotify API integration
├── playlist_generator.py # AI playlist generation logic
├── requirements.txt # Python dependencies
├── .env.example # Environment variables template
└── README.md # This file
📊 Data Storage
The application creates local JSON files for:
- User Data:
user_data_YYYYMMDD_HHMMSS.json- Spotify listening history - Playlist Data:
playlist_YYYYMMDD_HHMMSS.json- Generated playlist metadata
These files are used to improve recommendations and provide playlist history.
🔍 Logging
The application provides comprehensive logging:
- INFO: General application flow and successful operations
- WARNING: Non-critical issues (e.g., fallback to simple mode)
- ERROR: Critical errors and failures
Logs are output to console with timestamps and log levels.
⚙️ Fallback Modes
Without Gemini API
If the Gemini API is unavailable, the system falls back to:
- Simple keyword-based search query generation
- Popularity-based track selection with randomization
Without User Authentication
The system can still:
- Search for tracks using Spotify's public API
- Create playlists based on search results (with limited personalization)
🚨 Error Handling
The application includes robust error handling for:
- Authentication failures: Clear error messages and retry mechanisms
- API rate limits: Graceful degradation and retries
- Network issues: Timeout handling and fallback options
- Invalid inputs: Input validation and user-friendly error messages
🔒 Privacy & Security
- No persistent storage: User tokens are only kept in memory during the session
- Local data: All user data is stored locally on your machine
- Minimal scopes: Only requests necessary Spotify permissions
- Environment variables: Sensitive credentials stored in environment variables
📋 Requirements
Python Dependencies
fastmcp>=0.1.0
tekore>=4.0.0
google-generativeai>=0.3.0
asyncio
logging
typing
datetime
json
os
random
glob
System Requirements
- Memory: 512MB RAM minimum
- Storage: 100MB for application and data files
- Network: Stable internet connection for API calls
🐛 Troubleshooting
Common Issues
-
Authentication Error
- Check Spotify credentials in
.env - Verify redirect URI in Spotify app settings
- Ensure all required scopes are enabled
- Check Spotify credentials in
-
No Tracks Found
- Try more specific or different prompts
- Check internet connection
- Verify Spotify API access
-
Gemini API Errors
- Verify API key is correct
- Check API quota limits
- System will fallback to simple mode if needed
-
Port Already in Use
- Change PORT in
.envfile - Kill existing processes on the port
- Change PORT in
Debug Mode
Enable debug logging by modifying the logging level in main.py:
logging.basicConfig(level=logging.DEBUG)
🤝 Contributing
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
📜 License
This project is licensed under the MIT License - see the LICENSE file for details.
🙏 Acknowledgments
- Spotify Web API for music data and playlist management
- Google Gemini for AI-powered curation
- Tekore for elegant Spotify API integration
- FastMCP for MCP server implementation
📞 Support
For questions, issues, or feature requests:
- Check the Issues page
- Create a new issue with detailed information
- Include logs and error messages when reporting bugs
Made with ❤️ for music lovers and AI enthusiasts