Spotify MCP Server

PyPI

Сервер Model Context Protocol (MCP), предоставляющий инструменты для взаимодействия со Spotify Web API. Позволяет ИИ-ассистентам, таким как Claude, искать музыку, управлять воспроизведением, плейлистами и многим другим.

Возможности

Поиск — поиск треков, альбомов, исполнителей, плейлистов, шоу, эпизодов и аудиокниг
Управление воспроизведением — воспроизведение, пауза, пропуск, перемотка, громкость, перемешивание, повтор, управление очередью
Плейлисты — создание, обновление, добавление/удаление/изменение порядка треков
Библиотека — просмотр и управление сохраненными треками, альбомами, шоу, эпизодами и аудиокнигами
Обзор — получение сведений об альбомах, информации об исполнителях, метаданных треков
Подкасты и аудиокниги — просмотр шоу, эпизодов, аудиокниг и глав
Профиль пользователя — просмотр профиля, топ-исполнителей/треков, отслеживаемых исполнителей
44 инструмента, охватывающих все не устаревшие конечные точки Spotify Web API

Предварительные требования

uv — установите с помощью curl -LsSf https://astral.sh/uv/install.sh | sh
Учетная запись Spotify Developer
Приложение Spotify с Client ID и Client Secret

Получение учетных данных Spotify

Перейдите на панель управления разработчика Spotify
Нажмите Create App
Заполните данные приложения:
- App name: Выберите любое имя (например, "My MCP Server")
- App description: Необязательно
- Redirect URI: http://127.0.0.1:8888/callback
- Which API/SDKs are you planning to use?: Выберите Web API
Нажмите Save
На странице вашего приложения найдите Client ID
Нажмите Show client secret, чтобы увидеть ваш Client Secret

Важно: Redirect URI должен в точности совпадать с http://127.0.0.1:8888/callback (или тем, что вы указали в SPOTIFY_REDIRECT_URI). Не используйте localhost — используйте 127.0.0.1.

Установка

Выберите свой клиент ниже. Все примеры используют uvx для получения сервера по требованию — без клонирования и ручной установки.

Claude Code

claude mcp add spotify \
  -e SPOTIFY_CLIENT_ID=your_client_id \
  -e SPOTIFY_CLIENT_SECRET=your_client_secret \
  -- uvx mcp-server-spotify

Другие MCP-клиенты

Большинство MCP-клиентов настраивают серверы через JSON-файл. Добавьте эту запись в конфигурацию MCP вашего клиента:

{
  "mcpServers": {
    "spotify": {
      "command": "uvx",
      "args": ["mcp-server-spotify"],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id",
        "SPOTIFY_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Запуск из локальной копии

Для разработки или если вы хотите запустить измененную копию:

git clone https://github.com/llyfn/spotify-mcp.git
cd spotify-mcp && uv sync

Затем укажите своему клиенту путь к локальной копии вместо uvx:

"command": "uv",
"args": ["--directory", "/absolute/path/to/spotify-mcp", "run", "mcp-server-spotify"]

Конфигурация

Переменная	Обязательно	По умолчанию	Описание
`SPOTIFY_CLIENT_ID`	Да	—	Client ID вашего приложения Spotify
`SPOTIFY_CLIENT_SECRET`	Да	—	Client Secret вашего приложения Spotify
`SPOTIFY_REDIRECT_URI`	Нет	`http://127.0.0.1:8888/callback`	OAuth redirect URI

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

Сервер использует поток Authorization Code Spotify:

При первом использовании сервер открывает в вашем браузере страницу входа в Spotify
Spotify попросит вас одобрить доступ — сервер запрашивает все области (scopes), необходимые для полного набора инструментов (воспроизведение, библиотека, плейлисты и данные пользователя)
После авторизации Spotify перенаправляет на локальный сервер обратного вызова
Сервер обменивает код авторизации на токены доступа/обновления
Токены безопасно хранятся в ~/.spotify-mcp/credentials.json
Токены автоматически обновляются по истечении срока действия

При запуске в headless-среде (SSH, Docker) URL для авторизации будет выведен в stderr — скопируйте и вставьте его в браузер вручную.

Повторная аутентификация

Чтобы выполнить повторную аутентификацию (например, после отзыва доступа), удалите сохраненные учетные данные:

rm ~/.spotify-mcp/credentials.json

Доступные инструменты

Поиск

Инструмент	Описание
`search`	Поиск треков, альбомов, исполнителей, плейлистов, шоу, эпизодов или аудиокниг

Альбомы

Инструмент	Описание
`get_album`	Получение сведений об альбоме по ID
`get_album_tracks`	Получение треков в альбоме

Исполнители

Инструмент	Описание
`get_artist`	Получение сведений об исполнителе по ID
`get_artist_albums`	Получение альбомов исполнителя

Треки

Инструмент	Описание
`get_track`	Получение сведений о треке по ID

Плейлисты

Инструмент	Описание
`get_playlist`	Получение сведений о плейлисте
`update_playlist`	Обновление названия, описания или видимости плейлиста
`get_playlist_items`	Получение элементов плейлиста
`add_playlist_items`	Добавление треков/эпизодов в плейлист
`remove_playlist_items`	Удаление элементов из плейлиста
`reorder_playlist_items`	Изменение порядка элементов в плейлисте
`get_my_playlists`	Получение плейлистов текущего пользователя
`create_playlist`	Создание нового плейлиста

Библиотека

Инструмент	Описание
`get_saved_tracks`	Получение сохраненных треков
`get_saved_albums`	Получение сохраненных альбомов
`get_saved_shows`	Получение сохраненных шоу
`get_saved_episodes`	Получение сохраненных эпизодов
`get_saved_audiobooks`	Получение сохраненных аудиокниг
`save_to_library`	Сохранение элементов в библиотеку
`remove_from_library`	Удаление элементов из библиотеки
`check_saved_in_library`	Проверка наличия элементов в библиотеке

Плеер

Инструмент	Описание
`get_playback_state`	Получение текущего состояния воспроизведения
`get_currently_playing`	Получение текущего воспроизводимого трека
`play`	Запуск или возобновление воспроизведения
`pause`	Пауза воспроизведения
`next_track`	Пропуск к следующему треку
`previous_track`	Пропуск к предыдущему треку
`seek`	Перемотка к позиции в треке
`set_repeat`	Установка режима повтора (трек/контекст/выкл)
`set_volume`	Установка громкости воспроизведения
`toggle_shuffle`	Переключение режима перемешивания
`transfer_playback`	Перенос воспроизведения на другое устройство
`get_devices`	Получение доступных устройств
`add_to_queue`	Добавление элемента в очередь воспроизведения
`get_queue`	Получение очереди воспроизведения
`get_recently_played`	Получение недавно прослушанных треков

Шоу и подкасты

Инструмент	Описание
`get_show`	Получение сведений о шоу
`get_show_episodes`	Получение эпизодов шоу

Аудиокниги

Инструмент	Описание
`get_audiobook`	Получение сведений об аудиокниге
`get_audiobook_chapters`	Получение глав аудиокниги
`get_chapter`	Получение сведений о главе

Пользователи

Инструмент	Описание
`get_my_profile`	Получение профиля текущего пользователя
`get_my_top_items`	Получение топ-исполнителей или треков

Отслеживание исполнителей/пользователей использует те же инструменты save_to_library / remove_from_library / check_saved_in_library — передайте URI исполнителя или пользователя.

Участие в разработке

См. CONTRIBUTING.md для настройки среды разработки и руководств.

Лицензия

MIT — подробности см. в LICENSE.

mcp-server-spotify