Spotify Bulk Actions MCP

<!- - mcp-name: io.github.khglynn/spotify-bulk-actions-mcp - ->

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

What makes this different from other Spotify MCPs?

• 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

# Support This Project

Made cause I can't not have headphones on, support my 80k+ pocast subscriptions.

# Listed On

| Directory | Link |
|- -- -- -- -- --|- -- -- -|
| PyPI | pypi.org/project/spotify-bulk-actions-mcp |
| mcp.so | mcp.so/server/spotify-bulk-actions-mcp |
| awesome-mcp-servers | PR # 1541 (pending) |

# Projects I've Built With This

| Project | Description | Links |
|- -- -- -- --|- -- -- -- -- -- --|- -- -- --|
| recordOS | Which albums do you love most? A visual album collection app | Live · Repo |
| Festival Navigator | Navigate multi-day festivals with friends | Repo |

# # Playlists Maintained With This MCP

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

# 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

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

# Available Tools (18)

# # Library Analysis

| Tool | Description |
|- -- -- -|- -- -- -- -- -- --|
| check_auth_status | Verify Spotify auth is working |
| get_followed_artists | Get all artists you follow |
| get_saved_tracks | Get all your liked songs |
| get_library_artists | Artists from saved songs, ranked by count |
| get_albums_by_song_count | Albums with N+ saved songs |
| export_library_summary | Complete library export |

# # Search

| Tool | Description |
|- -- -- -|- -- -- -- -- -- --|
| search_track | Search for a single track |
| search_track_fuzzy | Broader search when exact fails |
| batch_search_tracks | Search many tracks with confidence scores |
| get_track_preview_url | Get 30-second preview URL |

# # Playlists

| Tool | Description |
|- -- -- -|- -- -- -- -- -- --|
| create_playlist | Create a new playlist |
| add_tracks_to_playlist | Add tracks to existing playlist |
| import_and_create_playlist | Full CSV → playlist workflow |
| create_playlist_from_search_results | Create from batch search |
| add_reviewed_tracks | Add reviewed/corrected tracks |
| get_playlist_info | Get playlist details |

# # Utilities

| Tool | Description |
|- -- -- -|- -- -- -- -- -- --|
| parse_song_list_csv | Validate a song CSV |
| export_review_csv | Export uncertain matches for review |

# 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

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

| Location | Purpose |
|- -- -- -- -- -|- -- -- -- --|
| .env | Your Spotify credentials (gitignored) |
| .spotify_cache/ | Auth tokens and cached data (gitignored) |
| src/server.py | Main MCP server |
| src/tools/ | Tool implementations |

# 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

# License

MIT

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