SpotifyMCP

MCP-сервер, который оборачивает Spotify Web API, позволяя ИИ-ассистентам (например, Claude) управлять воспроизведением, искать по всему каталогу, включая подкасты и аудиокниги, управлять вашей библиотекой и плейлистами, а также понимать ваши музыкальные предпочтения.

Почему именно этот

Большинство Spotify MCP-серверов — это тонкие обёртки. Этот создан, чтобы быть стандартным:

• Полная поверхность API — каждый не устаревший эндпоинт Spotify Web API, доступный со стандартным токеном разработчика, покрыт инструментом (воспроизведение, поиск, каталог, аудиокниги, персонализация, библиотека, плейлисты, подписки).

• Честность в отношении устаревших функций — Spotify удалил рекомендации, похожих исполнителей, аудио-характеристики/анализ, жанровые семена и рекомендуемые плейлисты из новых приложений. Серверы, которые всё ещё их предоставляют, поставляют инструменты, которые падают во время выполнения; этот — нет.

• Протестирован — полный набор модульных тестов для клиента (обновление токена, ограничение скорости, пагинация) и каждого обработчика инструментов, плюс сквозной смоук-тест протокола MCP. У многих альтернатив ноль тестов.

• Всё с пагинацией — fetch_all для списков библиотеки и плейлистов проходит по каждой странице (ограничение 500 элементов) вместо молчаливого обрезания на одной странице из 50.

• Подкасты — на первом месте — эпизоды работают везде: сейчас играет, очередь, поиск и воспроизведение. Некоторые конкуренты вообще не видят подкасты.

• Воспроизведение с учётом устройств — список устройств, перенос воспроизведения и нацеливание любой команды на конкретное устройство для много-комнатных конфигураций.

• Надёжная аутентификация — поток PKCE с тихим обновлением, постоянный кэш токенов с правами 600, безголовый поток вставки (SPOTIFY_HEADLESS=1) для серверов и контейнеров.

Related MCP server: Spotify MCP Server

Возможности

Воспроизведение (15 инструментов) — опросы «сейчас играет» / «текущее воспроизведение», воспроизведение (по URI или play_from_search для воспроизведения прямо по названию), пауза, пропуск, предыдущий трек, перемотка, громкость, перемешивание, повтор, просмотр/добавление в очередь, список устройств, перенос воспроизведения.

Поиск и каталог — единый поиск по трекам/исполнителям/альбомам/плейлистам/шоу/эпизодам; глубокие запросы для треков, исполнителей, альбомов исполнителя, альбомов, треков альбома, шоу, эпизодов шоу, эпизодов и вашего профиля (get_me).

Аудиокниги — названия, главы, поиск глав и сохранённые аудиокниги (ограничено рынком Spotify: США, Великобритания, Канада, Ирландия, Новая Зеландия, Австралия).

Персонализация — лучшие треки и исполнители за три временных диапазона, недавно прослушанное.

Библиотека — сохранённые треки/альбомы/шоу/эпизоды с опциональной полной пагинацией; единое сохранение/удаление/проверка через URI /me/library.

Плейлисты — полный CRUD плюс управление элементами (добавление/удаление/переупорядочивание), получение обложек и загрузка собственных обложек (требуется область ugc-image-upload для загрузки).

Подписки — список отслеживаемых исполнителей и проверка состояния подписки.

Также доступны: 7 ресурсов MCP (профиль, состояние плеера, очередь, лучшие треки/исполнители, недавно прослушанное, плейлисты) и 4 шаблона подсказок (диджей-сет, плейлист по настроению, сводка вкусов, альтернатива для открытий).

Требования и ограничения

• Для управления воспроизведением требуется Spotify Premium (воспроизведение, пауза, пропуск, перемотка, громкость, перемешивание, повтор, очередь, перенос). Бесплатные аккаунты могут аутентифицироваться и использовать инструменты поиска/каталога/библиотеки/плейлистов, но каждая команда воспроизведения завершится ошибкой от Spotify о необходимости Premium.

• Пагинация fetch_all проходит до 500 элементов за вызов (защита от бесконечных циклов); для большего используйте пагинацию limit/offset.

• Инструменты аудиокниг ограничены рынком Spotify: США, Великобритания, Канада, Ирландия, Новая Зеландия и Австралия.

• Режим разработчика Spotify позволяет до 5 авторизованных пользователей на приложение, пока не будет предоставлена расширенная квота.

Быстрая настройка

1. Создайте приложение Spotify

Каждому пользователю нужно собственное приложение Spotify, чтобы получить Client ID — так Spotify определяет, какое приложение отправляет API-запросы.

1. Перейдите в панель разработчика Spotify и создайте новое приложение.

2. В настройках приложения добавьте следующий Redirect URI точно (Spotify отклонит вход, если он не совпадает):

http://127.0.0.1:8888/callback

3. Сохраните. Скопируйте ваш Client ID.

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

Выполните команду ниже один раз, чтобы войти в свой аккаунт Spotify. Замените your_client_id_here на Client ID из шага 1. Она откроет окно браузера, и после вашего подтверждения сохранит токены в ~/.spotify-mcp/tokens.json. Сервер обновляет их автоматически — вам не нужно будет делать это снова.

macOS / Linux:

SPOTIFY_CLIENT_ID=your_client_id_here npx -y @novalux12/spotify-mcp@latest auth

Безголовые / удалённые хосты (нет браузера на машине, где запущен MCP-сервер):

SPOTIFY_HEADLESS=1 SPOTIFY_CLIENT_ID=your_client_id_here npx -y @novalux12/spotify-mcp@latest auth

URL аутентификации выводится; завершите поток в любом браузере (например, на ноутбуке), затем вставьте URL перенаправления обратно в подсказку. Полезно для домашних серверов, CI и сред выполнения агентов.

Безголовая аутентификация (хосты без браузера)

Если вы запускаете этот MCP-сервер на хосте без браузера (например, облачная ВМ, Docker-контейнер, удалённый сервер), установите переменную окружения SPOTIFY_HEADLESS=1. Поток аутентификации пропустит локальный HTTP-сервер обратного вызова и вместо этого предложит вставить URL перенаправления после авторизации приложения в вашем браузере.

Шаги

1. Установите SPOTIFY_HEADLESS=1 в вашем окружении

2. Запустите сервер — он выведет URL для авторизации приложения

3. Откройте URL в браузере на другой машине

4. После авторизации ваш браузер перенаправит на redirect URI

5. Скопируйте полный URL из адресной строки

6. Вставьте его обратно в подсказку сервера

Зачем

Стандартный поток аутентификации открывает браузер через пакет open и запускает локальный HTTP-сервер обратного вызова на 127.0.0.1:8888. Это ломается, когда MCP-сервер работает на безголовом хосте (домашний сервер, CI, среда выполнения агента), где нет браузера для open(), и обратный вызов 127.0.0.1:8888 недоступен с машины пользователя.

SPOTIFY_HEADLESS=1 переключает на поток вставки URL: URL аутентификации выводится в stdout, оператор завершает поток в любом браузере (ноутбук, телефон), затем вставляет полный URL перенаправления обратно. Код и состояние извлекаются и обмениваются на стороне сервера. Работает между машинами.

Windows (Command Prompt):

set SPOTIFY_CLIENT_ID=your_client_id_here && npx -y @novalux12/spotify-mcp@latest auth

Windows (PowerShell):

$env:SPOTIFY_CLIENT_ID="your_client_id_here"; npx -y @novalux12/spotify-mcp@latest auth

3. Настройка Claude Desktop

Откройте ваш claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: Откройте Claude Desktop → Настройки → Разработчик → Изменить конфигурацию

Добавьте блок mcpServers (замените your_client_id_here на ваш Client ID):

{
  "mcpServers": {
    "spotify": {
      "command": "npx",
      "args": ["-y", "@novalux12/spotify-mcp@latest"],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id_here"
      }
    }
  }
}

Полностью закройте и перезапустите Claude Desktop. Значок молотка в поле ввода чата подтверждает, что сервер подключён.

Альтернатива: Claude Code

Если вы используете Claude Code, добавьте сервер без ручного редактирования JSON:

claude mcp add spotify -- npx -y @novalux12/spotify-mcp@latest
# then set SPOTIFY_CLIENT_ID in your shell or MCP env:
export SPOTIFY_CLIENT_ID=your_client_id_here

Или добавьте его в .mcp.json в корне проекта — та же форма command/args/env, что и выше.

Команда для ИИ-агентов

Любой агент кодирования (Claude Code, OpenClaw, Cursor, Aider, …) может установить, собрать, аутентифицировать и зарегистрировать сервер одной вставкой. Дайте ему ваш Client ID и позвольте выполнить:

git clone https://github.com/NovaLux12/spotify-mcp-server.git && cd spotify-mcp-server \
  && npm ci && npm run build \
  && SPOTIFY_CLIENT_ID=your_client_id_here npm run auth

Затем укажите конфигурацию MCP вашего хоста на <repo>/dist/index.js с SPOTIFY_CLIENT_ID в его окружении (формы ниже). Агенты должны завершить, вызвав инструмент get_me один раз — это доказывает аутентификацию, области и транспорт за один цикл.

OpenClaw

Добавьте в mcp.servers в ~/.openclaw/openclaw.json:

"spotify": {
  "command": "node",
  "args": ["/path/to/spotify-mcp-server/dist/index.js"],
  "cwd": "/path/to/spotify-mcp-server",
  "env": { "SPOTIFY_CLIENT_ID": "your_client_id_here" }
}

Затем перезапустите шлюз OpenClaw, чтобы он перезапустил сервер. Безголовый хост? Выполните шаг аутентификации с SPOTIFY_HEADLESS=1 на любой машине с браузером (см. выше) — токены попадут в ~/.spotify-mcp/tokens.json в любом случае.

Когда что-то идёт не так: установите навык доктора

Этот репозиторий содержит skills/spotify-mcp-doctor/SKILL.md — процедурную диагностику, которую ваш агент может выполнить вместо того, чтобы вы перечитывали этот README. Он последовательно проходит реальные сценарии сбоев: подключение → бинарный файл → учётные данные приложения → свежесть токена → классификация ошибок (Premium против списка разрешений режима разработчика против ограничений рынка против устаревших функций). Установка:

cp -r skills/spotify-mcp-doctor ~/.openclaw/workspace/skills/   # OpenClaw
# or drop it into .claude/skills/ for Claude Code projects

Затем просто попросите вашего агента: «Инструменты Spotify не работают — запустите навык spotify doctor.»

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

После подключения вы можете просить Claude о таких вещах, как:

• «Какие мои лучшие треки в Spotify?»

• «Создай плейлист из спокойных lo-fi песен для учёбы»

• «Добавь песню Blinding Lights в мой плейлист для тренировок»

• «Каких исполнителей я слушал чаще всего в последнее время?»

• «Сделай мне плейлист с атмосферой ночной поездки»

Устранение неполадок

• «Не аутентифицирован» при первом вызове инструмента — выполните npx -y @novalux12/spotify-mcp@latest auth (или npm run auth из клона) и завершите поток в браузере. Токены хранятся в ~/.spotify-mcp/tokens.json и обновляются автоматически.

• Несовпадение Redirect URI — redirect URI приложения Spotify должен быть точно http://127.0.0.1:8888/callback (без завершающего слэша). Сохраните настройки приложения и повторите попытку.

• Порт 8888 занят — другой процесс удерживает порт обратного вызова; остановите его или выберите свободный порт через SPOTIFY_REDIRECT_URI=http://127.0.0.1:8888/callback с другим портом и соответствующим параметром в панели управления.

• Безголовый режим / Docker — установите SPOTIFY_HEADLESS=1 перед auth; вставьте URL перенаправления обратно по запросу (см. выше).

Отказ от ответственности

Это личный проект, не связанный со Spotify и не одобренный им. Он предоставляется как есть, без каких-либо гарантий. Используйте его ответственно и в соответствии с Условиями использования Spotify для разработчиков. Автор не несёт ответственности за любое неправильное использование или последствия, возникающие в результате использования этого программного обеспечения.

Разработка

git clone https://github.com/NovaLux12/spotify-mcp-server.git
cd spotify-mcp-server
npm install
npm run build

Скопируйте .env.example в .env и заполните ваш Client ID, затем:

npm run auth   # authenticate with Spotify
npm run dev    # run from source (no build needed)

Требуется Node 22.9+ (поддержка --env-file-if-exists). Файл .env не нужен — переменные окружения берутся из конфигурации хоста или командной строки.

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

npm test   # node:test runner — unit tests for the client and every tool module, plus an MCP protocol smoke test

Благодарности

• calebWei/SpotifyMCP — оригинальный поток аутентификации и каркас воспроизведения, из которых вырос этот проект.

• varunneal/spotify-mcp — эталонная реализация, использованная как планка качества для покрытия инструментов и эргономики.

Лицензия

MIT © Carme99 и участники NovaLux12.