spotify-mcp

Сервер MCP, который оборачивает spotipy, чтобы Claude (или любой MCP-клиент) мог искать в Spotify и читать плейлисты, сохранённые треки, каталоги исполнителей и сигналы обнаружения.

Создан специально как Spotify-бэкенд для re-com — по замыслу ориентирован на чтение, а не на управление воспроизведением. Он поддерживает создание плейлистов и добавление в них треков (так что список рекомендаций re-com может стать настоящим плейлистом), но управления воспроизведением/паузой/очередью здесь нет; для этого обратитесь к одному из нескольких существующих Spotify MCP-серверов, ориентированных на воспроизведение.

Инструменты

Реальное ограничение, если говорить прямо: Spotify ограничивает /recommendations и artist_related_artists для API-приложений, созданных после ноября 2024 года, у которых нет «Extended Quota Mode» (ручное одобрение, которое Spotify выдаёт неохотно). Если у вашего приложения его нет, get_recommendations и get_related_artists будут возвращать 403 — handle_errors превращает это в понятное сообщение, а не в сырой traceback, а spotify_client.py из re-com рассматривает это как недоступность одного сигнала, а не как фатальную ошибку. search_music, плейлисты, сохранённые треки и лучшие треки исполнителя не затрагиваются.

Другие проекты Claude Code на этой машине (например, re-com) вызывают эти инструменты, запуская этот сервер через MCP, а не обращаясь к spotipy/Spotify напрямую, — это единственное место, где хранятся учётные данные Spotify.

Настройка

1. Зарегистрируйте приложение Spotify

1. Перейдите в Spotify Developer Dashboard и создайте приложение.

2. Добавьте redirect URI, соответствующий SPOTIFY_REDIRECT_URI (по умолчанию http://127.0.0.1:8888/callback — вам не нужно, чтобы на этом порту что-то реально слушало; см. шаг 3).

3. Запишите Client ID и Client Secret приложения.

2. Установите зависимости

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

3. Аутентификация

export SPOTIFY_CLIENT_ID="..."
export SPOTIFY_CLIENT_SECRET="..."
python scripts/setup_auth_spotify.py

Это выводит URL авторизации, ожидает, пока вы войдёте и вставите обратно URL, на который вас перенаправило (отлично работает через SSH/в headless-режиме — ничему не нужно занимать порт редиректа), и записывает полученный токен в .spotify_cache (путь настраивается через SPOTIFY_CACHE_PATH).

.spotify_cache эквивалентен вашей вошедшей в систему сессии — никогда не коммитьте и не передавайте его. Он уже в .gitignore. Токены обновляются автоматически после кэширования; повторно запускайте этот скрипт, только если само обновление начинает давать сбои (например, был изменён client secret приложения или вы отозвали доступ в настройках аккаунта Spotify), или если SCOPE в server.py получает новые разрешения (сначала удалите .spotify_cache, чтобы поток авторизации снова запросил согласие — устаревший кэшированный токен не подхватит новые scope самостоятельно).

4. Добавление в Claude Code

claude mcp add spotify -s user \
  -e SPOTIFY_CLIENT_ID="..." \
  -e SPOTIFY_CLIENT_SECRET="..." \
  -e SPOTIFY_CACHE_PATH="$(pwd)/.spotify_cache" \
  -- "$(pwd)/.venv/bin/python" "$(pwd)/server.py"

-s user делает его доступным в любой сессии Claude Code, а не только в этом каталоге. Используйте абсолютные пути для интерпретатора python, server.py и SPOTIFY_CACHE_PATH, поскольку сервер может быть запущен из любого рабочего каталога.

Для других MCP-клиентов (Claude Desktop и т. д.) укажите им ту же команду и переменные окружения, используя их соответствующий формат конфигурации.

Тестирование

Модульные тесты (tests/) запускаются против написанного вручную фейкового клиента spotipy.Spotify — не требуется ни доступа к сети, ни учётных данных Spotify:

pip install -e ".[dev]"
pytest

Обработка ошибок

Вызовы инструментов преобразуют типичные сбои в понятные сообщения вместо сырых traceback:

• Отсутствующая/истёкшая авторизация (401) → сообщает, что нужно повторить шаг аутентификации.

• Ограничение/запрет (403) → сообщает, что это, скорее всего, ограничение доступа к Spotify API (см. примечание о рекомендациях/связанных исполнителях выше) или отсутствующий OAuth-scope.

• Ограничение частоты запросов (429) → сообщает, что нужно подождать, включая подсказку Retry-After, если Spotify её прислал.

• Любая другая ошибка API или OAuth сообщается напрямую, а не в виде сырого traceback.

Лицензия

MIT — см. LICENSE.