Spotify Bulk Actions MCP Server

How to use

You will use an MCP client to connect to this server and perform bulk Spotify tasks. Start by authenticating with Spotify, then run the MCP server locally and connect to it from your MCP client. You can fetch your library, run batch searches with confidence scores, and create playlists from search results. For uncertain matches, review and import them back into your library.

How to install

Prerequisites: ensure you have Python 3.10 or newer and a Spotify account. You also need Spotify Developer credentials.

1. Clone the project and enter the directory.

# Clone the repo
git clone https://github.com/khglynn/spotify-bulk-actions-mcp.git
cd spotify-bulk-actions-mcp

2. Create and activate a virtual environment, then install in editable mode.

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install the package
pip install -e .

3. Prepare environment variables. Copy the example and edit with your Spotify credentials.

cp .env.example .env
# Edit .env to set SPOTIFY_CLIENT_ID and SPOTIFY_CLIENT_SECRET

4. Authenticate with Spotify one time to obtain and store tokens.

python setup_auth.py
```
After login, tokens are saved locally in the .spotify_cache directory.

5. Run a quick check to ensure authentication is active.

source venv/bin/activate
python -c "from src.utils.auth import is_authenticated; print('Auth OK!' if is_authenticated() else 'Not authenticated')"

Additional setup for MCP client connection

You connect a client to the MCP server using a local stdio configuration. The README provides a ready-made setup for Claude Code that demonstrates how to link to the local Python runtime and the server script.

{
  "mcpServers": {
    "spotify": {
      "command": "/path/to/spotify-bulk-actions-mcp/venv/bin/python",
      "args": ["/path/to/spotify-bulk-actions-mcp/src/server.py"]
    }
  }
}

Connect to Claude Code

If you use Claude Code, add the following configuration to your settings to connect to the local MCP server.

{
  "mcpServers": {
    "spotify": {
      "command": "/path/to/spotify-bulk-actions-mcp/venv/bin/python",
      "args": ["/path/to/spotify-bulk-actions-mcp/src/server.py"]
    }
  }
}

check_auth_status

Verify Spotify authentication is functioning correctly for the connected MCP session.

get_followed_artists

Retrieve all artists you currently follow in Spotify.

get_saved_tracks

Fetch all your liked songs from your Spotify library.

get_library_artists

List artists from saved tracks, ranked by how many songs you have for each artist.

get_albums_by_song_count

Find albums that contain at least a specified number of saved songs.

export_library_summary

Export a comprehensive summary of your saved/library data.

search_track

Search for a single track by title and artist.

search_track_fuzzy

Perform a broader search when exact matches are not found.

batch_search_tracks

Search multiple tracks in bulk and return confidence scores per match.

get_track_preview_url

Obtain a 30-second preview URL for a track.

create_playlist

Create a new playlist in your Spotify account.

add_tracks_to_playlist

Add tracks to an existing playlist.

import_and_create_playlist

Process a CSV to create a new playlist from listed tracks.

create_playlist_from_search_results

Create a playlist directly from a set of search results.

add_reviewed_tracks

Add corrected or reviewed tracks back into a playlist or library.

get_playlist_info

Fetch details about a specified playlist.

parse_song_list_csv

Validate and parse a CSV of songs to be processed.

export_review_csv

Export uncertain matches for review and correction.