convez.ai
MCP ServerIntegração & APIsIntermediário
khglynn

Spotify Bulk Actions MCP

khglynn/spotify-bulk-actions-mcp

Automação em massa para playlists e bibliotecas do Spotify com validação humana

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP para operações em massa no Spotify, incluindo criação de playlists em lote, exportação de biblioteca e importação via CSV com scoring de confiança. Implementa revisão humana para correspondências incertas e gerenciamento eficiente de bibliotecas com 500+ músicas.

Instalação

$npx convez-ai khglynn/spotify-bulk-actions-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
2
Forks
2
Acompanhando
0
Saúde
42%
Último commit
há 2 dias
Versão
—
Issues abertas
5
Contribuidores
1

Casos de uso

  • Importar listas de músicas de podcasts automaticamente em playlists
  • Exportar e analisar sua biblioteca completa do Spotify
  • Criar playlists em lote a partir de arquivos CSV com validação de confiança
  • Identificar álbuns favoritos e artistas únicos na sua biblioteca

Veredito

MCP bem construído e especializado em automatizar workflows Spotify comuns. Destaca-se pelo sistema de confiança e revisão humana, evitando erros em correspondências de músicas — essencial para quem importa listas de podcasts ou mantém playlists complexas em escala.

README

A tradução para o português deste README ainda está na fila.

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


Listed On

DirectoryLink
PyPIpypi.org/project/spotify-bulk-actions-mcp
mcp.somcp.so/server/spotify-bulk-actions-mcp
awesome-mcp-serversPR #1541 (pending)

Projects I've Built With This

ProjectDescriptionLinks
recordOSWhich albums do you love most? A visual album collection appLive · Repo
Festival NavigatorNavigate multi-day festivals with friendsRepo

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

ToolDescription
check_auth_statusVerify Spotify auth is working
get_followed_artistsGet all artists you follow
get_saved_tracksGet all your liked songs
get_library_artistsArtists from saved songs, ranked by count
get_albums_by_song_countAlbums with N+ saved songs
export_library_summaryComplete library export

Search

ToolDescription
search_trackSearch for a single track
search_track_fuzzyBroader search when exact fails
batch_search_tracksSearch many tracks with confidence scores
get_track_preview_urlGet 30-second preview URL

Playlists

ToolDescription
create_playlistCreate a new playlist
add_tracks_to_playlistAdd tracks to existing playlist
import_and_create_playlistFull CSV → playlist workflow
create_playlist_from_search_resultsCreate from batch search
add_reviewed_tracksAdd reviewed/corrected tracks
get_playlist_infoGet playlist details

Utilities

ToolDescription
parse_song_list_csvValidate a song CSV
export_review_csvExport 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

LocationPurpose
.envYour Spotify credentials (gitignored)
.spotify_cache/Auth tokens and cached data (gitignored)
src/server.pyMain 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!

Ver o original no GitHub

Bom para

Relacionados