playlist-mcp

ghoshsoham71/playlist-mcp

3.2

If you are the rightful owner of playlist-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

Mood Playlist MCP Server is a Model Context Protocol server that generates mood-based music playlists using AI sentiment analysis and the Last.fm API.

Tools
3
Resources
0
Prompts
0

🎵 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

  1. Clone the repository

    git clone <your-repo-url>
cd spotify-playlist-generator

  2. Install dependencies

    pip install -r requirements.txt

  3. Set up environment variables

    cp .env.example .env
# Edit .env with your credentials

  4. 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

  1. Go to Spotify Developer Dashboard
  2. Create a new app
  3. Note your Client ID and Client Secret
  4. Add redirect URI: http://127.0.0.1:10000/callback
  5. Add the required scopes (handled automatically by the app)

Google Gemini API Setup

  1. Go to Google AI Studio
  2. Create a new API key
  3. Add the key to your .env file

📖 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 status
  • validate: Validate configuration
  • authenticate: Get Spotify authentication URL
  • fetch_data: Fetch and store user's Spotify data
  • generate_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

  1. Main Server (main.py): FastMCP server handling HTTP requests and routing
  2. Spotify Handler (spotify_handler.py): Spotify API integration using Tekore
  3. Playlist Generator (playlist_generator.py): AI-powered playlist curation using Gemini

Data Flow

  1. User provides natural language prompt
  2. Gemini AI generates relevant search queries
  3. Spotify API searches for matching tracks
  4. System fetches additional recommendations based on user history
  5. Gemini AI curates the final track selection
  6. 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

  1. Authentication Error

    • Check Spotify credentials in .env
    • Verify redirect URI in Spotify app settings
    • Ensure all required scopes are enabled

  2. No Tracks Found

    • Try more specific or different prompts
    • Check internet connection
    • Verify Spotify API access

  3. Gemini API Errors

    • Verify API key is correct
    • Check API quota limits
    • System will fallback to simple mode if needed

  4. Port Already in Use

    • Change PORT in .env file
    • Kill existing processes on the port

Debug Mode

Enable debug logging by modifying the logging level in main.py:

logging.basicConfig(level=logging.DEBUG)

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

📜 License

This project is licensed under the MIT License - see the file for details.

🙏 Acknowledgments

📞 Support

For questions, issues, or feature requests:

  1. Check the page
  2. Create a new issue with detailed information
  3. Include logs and error messages when reporting bugs

Made with ❤️ for music lovers and AI enthusiasts