spotify-library-mcp

Локальный MCP-сервер + CLI для управления собственной библиотекой Spotify. Однопользовательский, работает на вашей машине, PKCE-аутентификация (секрет клиента не нужен).

Настройка (один раз)

1. https://developer.spotify.com/dashboard → Создать приложение

   • Redirect URI: http://127.0.0.1:8888/callback

   • API: Web API

2. Скопируйте Client ID в .env (SPOTIFY_CLIENT_ID=...)

3. npm install && npm run auth → откроется браузер → подтвердите → refresh-токен будет записан в .env

4. Проверка: node bin/spot.js playlists

Related MCP server: Spotify MCP Server

Использование из Claude Code

.mcp.json в этой папке регистрирует сервер для этого проекта. Для каждого проекта:

claude mcp add --scope user spotify-library -- node /path/to/spotify-library-mcp/src/server.js

CLI

node bin/spot.js playlists
node bin/spot.js playlist <id>
node bin/spot.js rename <id> "New name"
node bin/spot.js merge '{"sourceIds":["a","b"],"newName":"Merged","deleteSources":true}'
node bin/spot.js delete <id>
node bin/spot.js top short_term 20
node bin/spot.js summary            # whole library
node bin/spot.js summary <id>       # one playlist
node bin/spot.js find "Sultans"     # which playlists contain it
node bin/spot.js dupes
node bin/spot.js diff <a> <b>
node bin/spot.js snapshot weekly && node bin/spot.js changes
node bin/spot.js rediscover 4 50

Инструменты

Плейлисты — list_playlists, get_playlist, create_playlist, update_playlist, add_tracks, remove_tracks, delete_playlist, merge_playlists Библиотека — get_saved_tracks, save_tracks, remove_saved_tracks, get_top_tracks, get_top_artists, get_recently_played Поиск — search, find_track (с проверкой исполнителя), get_search_budget, get_api_limits Аналитика (вычисляется на сервере, компактный вывод — то, о чём пользователи Spotify просили десять лет):

• summarize_library — понравившиеся треки вне плейлистов, заброшенные/пустые плейлисты, пересечения между плейлистами, десятилетия, дубликаты

• summarize_playlist — длительность, топ-исполнители, десятилетия, дубликаты, перепредставленность

• find_in_playlists — "в каком из моих плейлистов есть эта песня?"

• dedupe_report — одинаковые исполнитель+название, игнорируя суффиксы remaster/live/edit, с id для удаления

• playlist_diff — только в A / только в B / общие треки

• snapshot_library · list_snapshots · changes_since — резервная копия и "что изменилось с прошлого снимка" (переименования, добавления, удаления, лайки)

• rediscover — понравившиеся годы назад, отсутствующие в топ-треках и недавних прослушиваниях, распределённые по исполнителям

В моей библиотеке они нашли: 233 понравившихся трека не в плейлистах, 210 почти-дубликатов внутри плейлистов, 1,113 забытых лайков за 2018–2021.

Скрипты для библиотеки (как я реорганизовал 40 плейлистов → 9)

node scripts/pull.js library.json      # snapshot playlists + likes + tops
node scripts/build.js library.json     # file every track into genre collections (additive)
node scripts/moods.js                  # collapse genre collections into mood playlists
node scripts/curate.js library.json    # like picks, build Programming + שישי
node scripts/nostalgia.js library.json # 3-generation nostalgia
node scripts/explore.js library.json   # 🧭 Explore: ~400 new artists, many languages (search-heavy, resumable)
node scripts/genz.js                   # 🚗 Gen Z
node scripts/trending.js library.json  # 📈 Trending from live popularity

Списки исполнителей в scripts/classify.js и подобных скриптах — это мой вкус — форкните и отредактируйте. Каждый скрипт только добавляет; удаления — это отдельные явные вызовы spot delete.

Тесты

npm test прогоняет весь сценарий против мок-сервера Spotify в памяти (test/mock-spotify.js). Реальные учётные данные не затрагиваются.

Коннектор claude.ai (удалённый)

npm run tunnel запускает src/http.js (Streamable HTTP на /<MCP_SECRET>/mcp) вместе с быстрым туннелем Cloudflare и печатает URL, который нужно вставить в claude.ai → Настройки → Коннекторы → Добавить пользовательский коннектор (без OAuth; секретный путь — это шлюз).

Быстрые туннели при каждом запуске получают новый хостнейм. Для стабильного URL либо запустите именованный Cloudflare-туннель на своём домене, либо разверните src/http.js за вашим существующим обратным прокси (например, Nightscout box) с MCP_SECRET, SPOTIFY_CLIENT_ID, SPOTIFY_REFRESH_TOKEN в окружении.

Лимиты Spotify API (2026, приложения, созданные после ноября 2024) — вшито в клиент

Инструмент get_api_limits возвращает эту таблицу модели; instructions MCP-сервера тоже содержат сводку.

Поисковый бюджет (из опыта 2026-08-23)

~1,000 запросов к /search за один день дали этому приложению 429 с retry-after: 75469 (21 час). Ограничение per app (client id), не на фильтр, и это единственная квота, которая выдаёт исключение на день.

Вот что сервере делает в этом случае (src/budget.js, состояние — в .search-budget.json):

• считает запросы на каждый UTC-день и отказывает после SPOTIFY_SEARCH_DAILY_CAP (по умолчанию 800) с явной ошибкой

• кэширует каждый результат, поэтому повторный запуск скрипта стоит 0 запросов

• запоминает бан из длинного retry-after и быстро падает до его окончания — никаких 21-часовых ожиданий

• инструмент get_search_budget / функция searchBudget() сообщают остаток, кэш, время до конца бана

Пакетные скрипты (scripts/explore.js, genz.js, trending.js) сначала печатают бюджет, аккуратно останавливаются при лимите и продолжают при следующем запуске (пропуская то, что уже есть в плейлисте). Планируйте ≈ 250 поисков на скрипт в день — либо заведите второе приложение Spotify для поисковых задач.

План на завтра: бан истекает 2026-08-24 ~14:00 IDT → запускайте explore (≈400, на два дня) или укажите свежий client id.