Skip to main content
Glama
io.github.khglynn/spotify-bulk-actions-mcp

io.github.khglynn/spotify-bulk-actions-mcp

by 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. Buy Me A Coffee


Related MCP server: Tempo

Listed On


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

Listening Insights:

  • Your top artists and tracks (short/medium/long term)

  • Recently played history

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

Playlist Maintenance:

  • Find and remove duplicate tracks

  • Compare two playlists (shared vs unique tracks)

  • Bulk remove and reorder tracks, update playlist details

  • Export any playlist to CSV

Bulk Library Actions:

  • Follow/unfollow artists in bulk

  • Save/unsave tracks in bulk

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 spotify_bulk_actions_mcp.utils.auth import is_authenticated; print('Auth OK!' if is_authenticated() else 'Not authenticated')"

Option B: Hosted (claude.ai custom connector)

This server also runs as a remote MCP over streamable HTTP (MCP_TRANSPORT=http), fronted by OAuth 2.1 (WorkOS AuthKit) with a fail-closed user allowlist. That's how the author runs it: Cloud Run + Secret Manager for the Spotify refresh token, added to claude.ai as a custom connector. Tools carry readOnlyHint/destructiveHint annotations so clients can group read vs write actions. See Dockerfile and the deploy notes in the parent collection repo.

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/spotify-bulk-actions-mcp"
    }
  }
}

Restart Claude Code after adding this.

Available Tools (33)

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

Listening Insights

Tool

Description

get_top_artists

Your top artists (short/medium/long term)

get_top_tracks

Your top tracks (short/medium/long term)

get_recently_played

Recently played tracks

Bulk Library Actions

Tool

Description

follow_artists

Follow artists in bulk

unfollow_artists

Unfollow artists in bulk

save_tracks

Like/save tracks in bulk

unsave_tracks

Un-like tracks in bulk

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

Playlist Creation

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

Playlist Management

Tool

Description

get_playlist_info

Get playlist details

update_playlist

Update name, description, public status

get_playlist_tracks

Get all tracks in a playlist

export_playlist_to_csv

Export a playlist to CSV

compare_playlists

Shared vs unique tracks between two playlists

find_duplicate_tracks

Find duplicates in a playlist

remove_duplicate_tracks

Remove duplicates, keeping first occurrence

remove_tracks_from_playlist

Bulk remove specific tracks

reorder_playlist_tracks

Move tracks within a playlist

Utilities

Tool

Description

parse_song_list_csv

Validate a song CSV

export_review_csv

Export uncertain matches for review

How This Differs From the Official Spotify Connector

Claude has an official Spotify connector (built by Spotify, April 2026). It's excellent at what it does — but its tool surface is small, and this MCP exists for everything it doesn't cover. As of August 2026 the official connector exposes 8 tools: Search Spotify, Create Playlist, Get Currently Playing, Add to Library, Remove from Library, Fetch Playlist Tracks, and two auth utilities.

Capability

Official connector

This MCP

Search, playback context, mood playlists

✅

Search only

Create a playlist

✅

✅ (plus CSV import w/ confidence scoring)

Add/remove Liked Songs

✅ (one at a time)

✅ bulk

Read your full library (saved tracks, followed artists)

❌

✅

Listening insights (top artists/tracks, recently played)

❌

✅

Edit existing playlists (bulk remove, reorder, update details)

❌

✅

Dedupe / compare / export playlists to CSV

❌

✅

Bulk follow/unfollow artists

❌

✅

One more difference: the official connector runs on Spotify's partner-gated MCP gateway (no dynamic client registration; tokens from ordinary developer apps are rejected), so it's only usable inside partnered AI surfaces. This MCP runs under your own Spotify developer app — Development Mode limits apply (5 allowlisted users per Client ID as of February 2026), but you control it end to end.

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)

spotify_bulk_actions_mcp/server.py

Main MCP server

spotify_bulk_actions_mcp/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!

Available Tools

33 tools
add_reviewed_tracksA

Add tracks from a reviewed CSV to an existing playlist.

Use this after reviewing uncertain matches from a batch search.

The CSV should have an 'action' column:

  • 'approve': Add the matched track

  • 'reject': Skip this track

  • spotify:track:xxx: Use this specific URI instead

Inputs: playlist_id (required), reviewed_csv (required). Returns: object

add_tracks_to_playlistA

Add tracks to an existing playlist.

Handles batching automatically (Spotify max 100 per request).

Inputs: playlist_id (required), track_uris (required). Returns: object

batch_search_tracksA

Search for multiple tracks with confidence scoring.

Categorizes results:

  • HIGH (>= 90%): Safe to auto-add

  • MEDIUM (70-89%): Should review

  • LOW (< 70%): Needs attention

  • NOT FOUND: No results

Inputs: songs (required), delay_seconds. Returns: object

check_auth_statusA

Check if Spotify authentication is set up and working.

Returns current user info if authenticated.

Inputs: no named parameters. Returns: object

compare_playlistsB

Compare two playlists to find shared and unique tracks.

Inputs: playlist_id_1 (required), playlist_id_2 (required). Returns: object

create_playlistC

Create a new Spotify playlist.

Inputs: name (required), description, public. Returns: object

create_playlist_from_search_resultsB

Create a playlist from batch search results.

Inputs: name (required), batch_results (required), include_confidence, description, +1 more. Returns: object

export_library_summaryA

Export a complete summary of your Spotify library.

Includes:

  • Followed artists

  • Top artists by saved song count

  • Albums with most saved songs

Inputs: use_cache. Returns: object

export_playlist_to_csvA

Export a playlist to CSV format.

Great for backing up playlists or sharing song lists.

Inputs: playlist_id (required). Returns: object

export_review_csvA

Export medium/low confidence matches to a CSV for human review.

Inputs: batch_results (required). Returns: object

find_duplicate_tracksB

Find duplicate tracks in a playlist.

Inputs: playlist_id (required). Returns: object

follow_artistsB

Follow artists on Spotify.

Inputs: artist_ids (required). Returns: object

get_albums_by_song_countA

Find albums where you have N or more saved songs.

Great for finding albums worth buying on vinyl!

Inputs: min_songs, use_cache. Returns: object

get_followed_artistsB

Get all artists you follow on Spotify.

Inputs: use_cache. Returns: object

get_library_artistsA

Get unique artists from your saved songs, sorted by song count.

This shows artists you have saved songs from (even if not followed), ranked by how many songs you've saved.

Inputs: use_cache. Returns: object

get_playlist_infoC

Get information about a playlist.

Inputs: playlist_id (required). Returns: object

get_playlist_tracksA

Get all tracks from a playlist.

Inputs: playlist_id (required). Returns: object

get_recently_playedC

Get your recently played tracks.

Inputs: limit. Returns: object

get_saved_tracksA

Get all your liked/saved songs on Spotify.

Note: This may take 1-2 minutes for large libraries (10k songs).

Inputs: use_cache. Returns: object

get_top_artistsA

Get your top artists based on listening history.

Great for understanding your music taste and finding festival lineups.

Inputs: time_range, limit. Returns: object

get_top_tracksA

Get your top tracks based on listening history.

Inputs: time_range, limit. Returns: object

get_track_preview_urlA

Get the 30-second preview URL for a track.

Inputs: track_uri (required). Returns: object

import_and_create_playlistA

Full workflow: Parse song list CSV, search all tracks, create playlist.

This is the main tool for bulk playlist creation from a list of songs.

Inputs: name (required), csv_content (required), include_confidence, description, +1 more. Returns: object

parse_song_list_csvA

Parse a CSV of songs into a structured list.

Use this to validate your CSV before batch searching.

Inputs: csv_content (required). Returns: object

remove_duplicate_tracksA

Remove duplicate tracks from a playlist, keeping the first occurrence.

For safety, returns a preview unless confirm=True.

Inputs: playlist_id (required), confirm. Returns: object

remove_tracks_from_playlistA

Remove specific tracks from a playlist.

For safety, returns a preview unless confirm=True.

Inputs: playlist_id (required), track_uris (required), confirm. Returns: object

reorder_playlist_tracksC

Move tracks within a playlist.

Inputs: playlist_id (required), range_start (required), insert_before (required), range_length. Returns: object

save_tracksA

Save tracks to your Spotify library (like/heart them).

Inputs: track_ids (required). Returns: object

search_trackC

Search for a single track and get matches with confidence scores.

Inputs: title (required), artist (required), limit. Returns: object

search_track_fuzzyA

Broader fuzzy search when exact match fails.

Tries multiple strategies:

  1. Exact title + artist

  2. Title only

  3. Simplified title (removing parentheses, etc.)

Inputs: title (required), artist (required), limit. Returns: object

unfollow_artistsA

Unfollow artists on Spotify.

For safety, returns a preview unless confirm=True.

Inputs: artist_ids (required), confirm. Returns: object

unsave_tracksA

Remove tracks from your Spotify library.

For safety, returns a preview unless confirm=True.

Inputs: track_ids (required), confirm. Returns: object

update_playlistB

Update playlist details (name, description, public status).

Only provide the fields you want to change.

Inputs: playlist_id (required), name, description, public. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 33 tools

    Disambiguation5/5

    Each tool has a clearly defined purpose, with distinct boundaries between batch search, single search, fuzzy search, and playlist operations. The descriptions provide clear differentiation, even for similar tools like batch_search_tracks and search_track.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern, using underscores and descriptive verbs. There are no mixed conventions or vague names, making the toolset predictable for an agent.

    Tool Count4/5

    With 33 tools, the count is high but justified by the comprehensive scope of bulk Spotify operations, including search, playlist management, library actions, and CSV workflows. It is slightly above the typical range but each tool serves a distinct purpose.

    Completeness5/5

    The tool set covers the full lifecycle of bulk actions: authentication, search with confidence scoring, playlist creation and modification, duplicate management, library operations, and CSV import/export. No obvious gaps are present for the stated purpose.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      An MCP server that enables users to control Spotify playback, search music, and manage playlists through natural conversation. It is updated for the February 2026 Spotify Web API changes and supports full playlist CRUD operations.
      6
      8
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server for Spotify control and synchronized lyrics retrieval that enables playback management, queue navigation, and music search capabilities. It also features perception tools for real-time track analysis, including BPM, key detection, and timestamped lyrics.
      72 npm
      3
      Apache 2.0
    • A
      license
      Not graded
      quality
      F
      maintenance
      An MCP server that enables users to control Spotify playback, search for music, and manage playlists through MCP-compatible clients. It supports features like track recommendations and playback management using secure OAuth authentication.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A remote MCP server for Spotify with brokered OAuth and server-side intelligence, enabling search, playlist management, playback control, library analysis, and listening trends via natural language.
      127 npm
      4
      MIT