Spotify Bulk Actions

This Spotify Bulk Actions MCP server enables bulk Spotify operations through a Model Context Protocol interface, focusing on batch playlist creation, library exports, and large-scale library management. It emphasizes confidence scoring for bulk searches, human-in-the-loop review for uncertain matches, and built-in rate limiting to efficiently handle 500+ song operations while exporting and importing library data as needed.

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"] } } }

## Available tools

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