Melody

A Model Context Protocol (MCP) server that exposes Spotify playback controls, playlist generation, music discovery, and web search tools for integration with Large Language Models.

Features

🔐 Built-in Authentication

• Automatic Spotify OAuth flow with browser-based login
• Secure token management and refresh
• No manual token handling required

Spotify Playback Controls

• Play specific tracks
• Pause/resume playback
• Skip tracks (next/previous)
• Control volume
• Manage playback queue
• Get currently playing track
• Device management

Playlist Management

• Create playlists from prompts using AI
• Generate playlists based on listening history
• Create playlists from provided tracks or artists
• Search for tracks and artists (no auth required)

Music Discovery

• Intelligent music search using Last.fm API
• Get top tracks by genre/tag
• Find similar artists and tracks
• Get artist top tracks

Web Search

• Google Custom Search integration for music-related queries

Quick Start

1. Install dependencies:

npm install

2. Configure environment variables:

cp env.example .env
# Edit .env with your API keys

3. Start the server:

npm start

4. Authenticate with Spotify (when prompted by Claude):
   • Use the spotify_authenticate tool
   • Browser will open automatically for Spotify login
   • Complete the OAuth flow
   • Return to Claude Desktop to use playback features

Authentication Flow

The MCP server includes a built-in authentication system:

1. Check Authentication Status:

   Use: spotify_check_auth
   

2. Login to Spotify:

   Use: spotify_authenticate
   

   • Opens browser automatically
   • Complete Spotify OAuth
   • Tokens managed automatically

3. Logout:

   Use: spotify_logout
   

Tool Categories

🔐 Authentication Tools (3 tools)

• spotify_authenticate - Login to Spotify
• spotify_check_auth - Check authentication status
• spotify_logout - Logout from Spotify

🎵 Playback Controls (11 tools - require authentication)

• spotify_play_track - Play specific tracks
• spotify_pause/resume - Control playback
• spotify_skip_next/previous - Track navigation
• spotify_set_volume - Volume control
• spotify_add_to_queue - Queue management
• spotify_get_currently_playing - Current track info
• spotify_get_devices - Device management
• spotify_transfer_playback - Switch devices
• spotify_seek - Position control

🔍 Search Tools (2 tools - no authentication required)

• spotify_search_track - Find tracks
• spotify_search_artist - Find artists

📝 Playlist Generation (3 tools)

• playlist_create_from_prompt - AI-generated from text
• playlist_create_from_tracks - Based on provided tracks
• playlist_create_from_artists - Based on provided artists

🎼 Music Discovery (4 tools)

• music_discovery_search - Intelligent Last.fm search
• music_discovery_by_genre - Genre-based discovery
• music_discovery_similar_artist - Find similar artists
• music_discovery_artist_top_tracks - Artist's popular songs

🌐 Web Search (1 tool)

• web_search - Google Custom Search integration

Total: 24 tools

Configuration

Create a .env file in the root directory with the following variables:

# Spotify API Credentials
SPOTIFY_CLIENT_ID=your_spotify_client_id
SPOTIFY_CLIENT_SECRET=your_spotify_client_secret

# Last.fm API (for music discovery)
LASTFM_API_KEY=your_lastfm_api_key

# Google Search API (for web search)
GOOGLE_SEARCH_API_KEY=your_google_search_api_key
GOOGLE_SEARCH_CX_ID=your_google_search_cx_id

# OpenAI API Key (for playlist generation)
OPENAI_API_KEY=your_openai_api_key

Getting API Keys

Spotify API

1. Go to Spotify Developer Dashboard
2. Create a new app
3. Copy the Client ID and Client Secret

Last.fm API

1. Go to Last.fm API
2. Create an API account
3. Copy the API key

Google Custom Search API

1. Go to Google Cloud Console
2. Enable the Custom Search API
3. Create credentials and copy the API key
4. Set up a Custom Search Engine at Google CSE

OpenAI API

1. Go to OpenAI Platform
2. Create an API key

Usage with MCP Clients

This server can be integrated with any MCP-compatible client. The server exposes tools for:

• spotify_play_track - Play a specific track
• spotify_pause - Pause playback
• spotify_resume - Resume playback
• spotify_skip_next - Skip to next track
• spotify_skip_previous - Skip to previous track
• spotify_set_volume - Set playback volume
• spotify_add_to_queue - Add track to queue
• spotify_get_currently_playing - Get current track info
• spotify_search_track - Search for tracks
• spotify_search_artist - Search for artists
• playlist_create_from_prompt - Generate playlist from text prompt
• playlist_create_from_tracks - Create playlist from provided tracks
• playlist_create_from_artists - Create playlist from provided artists
• music_discovery_search - Intelligent music search
• music_discovery_by_genre - Get tracks by genre
• music_discovery_similar_artist - Find similar artists
• music_discovery_artist_top_tracks - Get artist's top tracks
• web_search - Perform web search

Authentication

For Spotify functionality, you'll need to provide a valid Spotify access token. The server expects this to be passed as a parameter to Spotify-related tools.

License

MIT