danisss9/spotify-playlist-generator-mcp-server

Spotify Playlist Generator MCP Server

A Model Context Protocol (MCP) server that enables AI applications to search for music tracks and manage playlists using the official Spotify Web API.

Features

• Search Music Tracks: Find music tracks on Spotify with customizable search parameters
• Get Track Details: Retrieve comprehensive information about specific tracks
• Get Playlist Tracks: List tracks from playlists
• Playlist Management: Complete playlist management including creating, editing, and managing playlists (requires OAuth setup)

Setup

Prerequisites

• Node.js 18 or higher
• A Spotify Developer Account
• Spotify App credentials (Client ID and Client Secret)

Installation

1. Clone this repository:

git clone https://github.com/danisss9/spotify-playlist-generator-mcp-server

2. Install dependencies:

npm install

3. Create a Spotify App:

   • Go to the Spotify Developer Dashboard
   • Create a new app
   • Note down your Client ID and Client Secret
   • Add http://localhost:8888/callback to your redirect URIs

4. Set up environment variables:

# Create a .env file
echo "SPOTIFY_CLIENT_ID=your_client_id_here" > .env
echo "SPOTIFY_CLIENT_SECRET=your_client_secret_here" >> .env

5. Build the TypeScript code:

npm run build

Running the Server

For development with auto-rebuild:

npm run dev

For production:

npm start

Using with MCP Clients

This server uses the stdio transport, so it can be used with any MCP client that supports stdio.

Claude Desktop Configuration

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "spotify-playlist-generator": {
      "command": "node",
      "args": ["/absolute/path/to/spotify-playlist-generator/build/index.js"],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id_here",
        "SPOTIFY_CLIENT_SECRET": "your_client_secret_here"
      }
    }
  }
}

Visual Studio Code with GitHub Copilot Configuration

To use this MCP server with GitHub Copilot in Visual Studio Code, you need to configure it in your VS Code settings:

1. Open VS Code Settings: Press Ctrl+, (Windows/Linux) or Cmd+, (macOS)

2. Search for MCP: Type "mcp" in the search bar

3. Add MCP Server Configuration: Add the following to your VS Code settings JSON:

{
  "github.copilot.chat.mcp.servers": {
    "spotify-playlist-generator": {
      "command": "node",
      "args": ["/absolute/path/to/spotify-playlist-generator/build/index.js"],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id_here",
        "SPOTIFY_CLIENT_SECRET": "your_client_secret_here"
      }
    }
  }
}

Alternative: Use Settings UI

1. Go to File > Preferences > Settings (or use Ctrl+,)
2. Search for "GitHub Copilot MCP"
3. Click "Edit in settings.json" next to "Github › Copilot › Chat: Mcp Servers"
4. Add the server configuration as shown above

Environment Variables Setup

For security, you can also set environment variables system-wide instead of in the config:

Windows (PowerShell):

[Environment]::SetEnvironmentVariable("SPOTIFY_CLIENT_ID", "your_client_id_here", "User")
[Environment]::SetEnvironmentVariable("SPOTIFY_CLIENT_SECRET", "your_client_secret_here", "User")

Windows (Command Prompt):

setx SPOTIFY_CLIENT_ID "your_client_id_here"
setx SPOTIFY_CLIENT_SECRET "your_client_secret_here"

macOS/Linux:

export SPOTIFY_CLIENT_ID="your_client_id_here"
export SPOTIFY_CLIENT_SECRET="your_client_secret_here"
# Add to ~/.bashrc, ~/.zshrc, or ~/.profile to persist
echo 'export SPOTIFY_CLIENT_ID="your_client_id_here"' >> ~/.bashrc
echo 'export SPOTIFY_CLIENT_SECRET="your_client_secret_here"' >> ~/.bashrc

Then remove the env section from the VS Code configuration:

{
  "github.copilot.chat.mcp.servers": {
    "spotify-playlist-generator": {
      "command": "node",
      "args": ["/absolute/path/to/spotify-playlist-generator/build/index.js"]
    }
  }
}

Usage in VS Code

Once configured, you can use the MCP server through GitHub Copilot Chat:

1. Open Copilot Chat (Ctrl+Alt+I or click the chat icon)
2. Use natural language to interact with Spotify:
   • "Search for jazz music tracks"
   • "Create a new playlist called 'My Favorites'"
   • "Add these tracks to my playlist"
   • "Show me details about this Spotify track"

Available Tools

OAuth-Required Tools (All features require authentication)

authenticate_spotify

Authenticate with Spotify OAuth to enable music search and playlist management features.

Parameters:

• getAuthUrl (boolean, default: false): Set to true to get the authorization URL
• authCode (string, optional): Authorization code from OAuth flow

get_auth_status

Check current Spotify authentication status.

Parameters: None

search_tracks

Search Spotify for music tracks.

Parameters:

• query (string): Search query for tracks
• limit (number, 1-50, default: 20): Maximum number of results
• market (string, optional): ISO 3166-1 alpha-2 country code to filter results

get_track_details

Get detailed information about a specific Spotify track.

Parameters:

• trackId (string): Spotify track ID
• market (string, optional): ISO 3166-1 alpha-2 country code for market

create_playlist

Create a new Spotify playlist (requires authentication).

Parameters:

• name (string): Playlist name
• description (string, optional): Playlist description
• public (boolean, default: false): Whether the playlist should be public
• collaborative (boolean, default: false): Whether the playlist should be collaborative

edit_playlist

Edit existing playlist information (requires authentication).

Parameters:

• playlistId (string): ID of the playlist to edit
• name (string, optional): New name for the playlist
• description (string, optional): New description for the playlist
• public (boolean, optional): New public setting
• collaborative (boolean, optional): New collaborative setting

Note: At least one field (name, description, public, or collaborative) must be provided to update.

add_to_playlist

Add tracks to a Spotify playlist (requires authentication).

Parameters:

• playlistId (string): Target playlist ID
• trackUris (array of strings): Array of Spotify track URIs to add
• position (number, optional): Position to insert tracks (0-based index)

list_playlists

List user's Spotify playlists (requires authentication).

Parameters:

• limit (number, 1-50, default: 20): Maximum number of playlists
• offset (number, min: 0, default: 0): Index offset for pagination

get_playlist_tracks

Get tracks from a Spotify playlist (requires authentication).

Parameters:

• playlistId (string): ID of the playlist to get tracks from
• limit (number, 1-100, default: 50): Maximum number of tracks to return
• offset (number, min: 0, default: 0): Index offset for pagination

remove_from_playlist

Remove tracks from a Spotify playlist (requires authentication).

Parameters:

• playlistId (string): ID of the playlist to remove tracks from
• trackUris (array of strings): Array of Spotify track URIs to remove
• snapshotId (string, optional): Playlist snapshot ID for version control

OAuth Authentication Setup

For all functionality, you need to set up OAuth 2.0 with Spotify:

1. Spotify Developer Dashboard Setup

1. Go to Spotify Developer Dashboard
2. Log in with your Spotify account
3. Click "Create an App"
4. Fill in app name and description
5. Add http://localhost:8888/callback to redirect URIs
6. Copy your Client ID and Client Secret

2. Environment Configuration

Add your OAuth credentials to the .env file:

SPOTIFY_CLIENT_ID=your_client_id_here
SPOTIFY_CLIENT_SECRET=your_client_secret_here

3. Authentication Flow

1. Use the authenticate_spotify tool with getAuthUrl: true
2. Open the provided URL in your browser
3. Sign in to your Spotify account and grant permissions
4. Copy the authorization code from the callback URL
5. Use authenticate_spotify tool again with the authCode parameter

4. Using Authenticated Features

Once authenticated, you can:

• Search for music tracks
• Get detailed track information
• Create new playlists
• Edit existing playlist information (name, description, privacy)
• Add tracks to your playlists
• List your playlists
• Get tracks from playlists
• Remove tracks from playlists

API Limitations

• Rate Limiting: Spotify API has rate limits (varies by endpoint)
• OAuth Tokens: Access tokens expire after 1 hour and need refresh
• Market Restrictions: Some tracks may not be available in certain markets
• Permissions: OAuth scope determines available operations

Development

Building

npm run build

Development Mode

npm run dev

Project Structure

src/
└── index.ts          # Main server implementation

build/                # Compiled JavaScript output

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

License

MIT License - see LICENSE file for details

Troubleshooting

Common Issues

1. "SPOTIFY_CLIENT_ID and SPOTIFY_CLIENT_SECRET environment variables are required"

   • Make sure you've set both environment variables
   • Verify the credentials are valid from your Spotify app

2. "Authentication required" errors

   • Use the authenticate_spotify tool to authenticate first
   • Check if your access token has expired and re-authenticate

3. "Rate limit exceeded" errors

   • Wait for the rate limit to reset
   • Reduce the frequency of API calls

4. Build errors

   • Make sure you have Node.js 18+ installed
   • Run npm install to ensure all dependencies are installed
   • Check TypeScript compilation with npm run build

5. "Track not available" errors

   • Some tracks may not be available in your market
   • Try specifying a different market parameter

Security Considerations

• Never commit API keys to version control
• Use environment variables for sensitive configuration
• Validate all user inputs
• Implement proper error handling and logging
• Be mindful of Spotify's API terms of service

This project was created using GitHub Copilot