Spotify Bulk Actions MCP

🚀 Spotify Bulk Actions MCP

A Model Context Protocol (MCP) server for bulk Spotify operations, enabling batch playlist creation, library exports, and large - scale library management.

🚀 Quick Start

1. Prerequisites

• Python 3.10+
• A Spotify account
• Spotify Developer credentials (get them here)

2. Clone & Setup

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

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

# Install the package
pip install -e .

# Copy env example and add your credentials
cp .env.example .env
# Edit .env with your SPOTIFY_CLIENT_ID and SPOTIFY_CLIENT_SECRET

Also on PyPI: pip install spotify-bulk-actions-mcp - but you'll still need local .env and auth setup.

3. Authenticate with Spotify (One-Time)

This opens a browser for you to log in:

python setup_auth.py

After login, your token is saved locally in .spotify_cache/.

4. Test It Works

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

5. Connect to Claude Code

Add this to your Claude Code settings (~/.claude/settings.local.json):

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

Restart Claude Code after adding this.

✨ Features

• Confidence scoring: Batch searches return HIGH/MEDIUM/LOW confidence for each match.
• Human-in-the-loop: Uncertain matches are exported for review, then re - imported.
• Bulk operations: Handle 500+ songs efficiently with rate limiting built - in.
• Library exports: Export your complete library data.
• Podcast playlist focused: Built specifically for importing song lists from podcast show notes.

📦 Installation

As shown in the Quick Start section, you can clone the repository and install the package using pip install -e ., or install it from PyPI using pip install spotify-bulk-actions-mcp. Remember to set up your .env file and authenticate with Spotify.

💻 Usage Examples

Basic Usage

Let's take getting library stats as an example. Ask Claude:

"What artists do I have the most saved songs from?" Claude will use get_library_artists and show you the result.

Advanced Usage

For creating a bulk podcast playlist:

1. Ask Claude to use batch_search_tracks with your song list.
2. Review the results (HIGH - confidence matches go in automatically).
3. Use export_review_csv to get uncertain matches.
4. Review/correct in a spreadsheet.
5. Use add_reviewed_tracks to add your corrections.

📚 Documentation

What This Does

Library Analysis

• Get all your followed artists.
• Get all saved/liked songs (handles libraries up to 10k songs).
• Find unique artists from your library ranked by song count.
• Find albums where you have 6+ saved songs (great for vinyl shopping!).
• Export your complete library summary.

Bulk Playlist Creation

• Import song lists from CSV files (for podcast playlists, etc.).
• Batch search with confidence scoring (HIGH/MEDIUM/LOW).
• Automatic handling of uncertain matches for human review.
• Create playlists from search results.

Available Tools (18)

Library Analysis

Search

Playlists

Utilities

Example Workflows

Get Your Library Stats

Ask Claude:

"What artists do I have the most saved songs from?" Claude will use get_library_artists and show you.

Find Albums for Vinyl

Ask Claude:

"Find albums where I have 6 or more saved songs" Claude will use get_albums_by_song_count with min_songs = 6.

Create Playlist from Song List

1. Create a CSV file:

title,artist
Bohemian Rhapsody,Queen
Hotel California,Eagles
Billie Jean,Michael Jackson

2. Ask Claude:

"Create a playlist called 'My Mix' from this CSV: [paste CSV]" Claude will:

1. Parse the CSV.
2. Search each song with confidence scoring.
3. Create the playlist with high - confidence matches.
4. Show you uncertain matches to review.

Bulk Podcast Playlist

For large lists (500+ songs):

1. Ask Claude to use batch_search_tracks with your song list.
2. Review the results (HIGH goes in automatically).
3. Use export_review_csv to get uncertain matches.
4. Review/correct in a spreadsheet.
5. Use add_reviewed_tracks to add your corrections.

Rate Limits

The server handles Spotify's rate limits automatically:

• Small delays between API calls.
• Automatic retry on 429 errors.
• Caching to reduce repeat calls. For 10k songs, expect the initial library fetch to take 2 - 3 minutes.

Files & Data

Troubleshooting

"Not authenticated" error:

python setup_auth.py

Rate limit errors: Wait a few minutes and try again. The server will auto - retry. Token expired: The server auto - refreshes tokens. If issues persist, re - run setup_auth.py.

Security Notes

• Your credentials are in .env (gitignored, never committed).
• Auth tokens are stored locally in .spotify_cache/.
• Never share your .env or token files.
• If credentials are exposed, rotate them in Spotify Dashboard.

Listed On

Projects I've Built With This

Playlists Maintained With This MCP

Coming soon: Switched On Pop, This American Life, and more podcast playlists

📄 License

MIT

Made cause I can't not have headphones on. If this helps you, buy me a coffee!