spotify-mcp

Сервер Model Context Protocol (MCP), который связывает Claude со Spotify. Управляйте воспроизведением Spotify, ищите музыку, управляйте плейлистами и многое другое — и все это через естественное общение с Claude.

Примечание о форке: Этот проект является форком varunneal/spotify-mcp и обновлен для изменений в Spotify Web API от февраля 2026 года. Создан и поддерживается с помощью Claude Code.

Что изменилось (v0.4.0)

Переработка архитектуры

• Удален spotipy — теперь используется httpx напрямую (нативный асинхронный режим, без обертки asyncio.to_thread)

• Единый модуль — server.py, spotify_api.py, utils.py объединены в один файл

• FastMCP — чистые декораторы @mcp.tool() вместо ручного ToolModel + маршрутизации match/case

• 2 зависимости — только mcp + httpx (было mcp + spotipy + python-dotenv)

• Явная OAuth — spotify-mcp --auth для первоначальной настройки, автоматическое обновление при последующем использовании

Функции (сохранены из v0.3.0)

• Запуск, пауза и пропуск воспроизведения

• Поиск треков, альбомов, исполнителей и плейлистов

• Получение подробной информации о любом элементе Spotify

• Управление очередью воспроизведения

• Полный CRUD плейлистов (создание, чтение, обновление, удаление треков)

• Получение понравившихся/сохраненных песен с опциональным обогащением жанрами

• Адаптировано для изменений API Spotify от февраля 2026 года

Related MCP server: Spotify MCP Server

Как это работает

Claude <--MCP (stdio)--> spotify-mcp <--httpx async--> Spotify Web API

1. Claude отправляет вызовы инструментов через протокол MCP

2. Сервер переводит их в запросы к Spotify Web API с использованием httpx

3. Токены OAuth обновляются автоматически; первоначальная авторизация через spotify-mcp --auth

4. Результаты парсятся в лаконичный JSON и возвращаются в Claude

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

Архитектура

src/spotify_mcp/
  __init__.py   # Entry point (stdio / --auth)
  server.py     # FastMCP server, API client, parsers — all in one

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

• Python 3.12+

• Аккаунт Spotify Premium (требуется для доступа к API в режиме разработчика с февраля 2026 года)

• Учетные данные Spotify Developer App

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

1. Создание приложения Spotify Developer

1. Перейдите на developer.spotify.com/dashboard

2. Создайте новое приложение

3. Установите URI перенаправления на http://127.0.0.1:8080/callback

4. Запишите свой Client ID и Client Secret

Важно (февраль 2026): Приложения в режиме разработчика ограничены 5 авторизованными пользователями и требуют, чтобы у владельца приложения была подписка Spotify Premium.

2. Первоначальная аутентификация

Запустите процесс аутентификации один раз, чтобы получить токен OAuth:

SPOTIFY_CLIENT_ID=your_id SPOTIFY_CLIENT_SECRET=your_secret uv run spotify-mcp --auth

Это откроет браузер для входа в Spotify, а затем сохранит токен в ~/.spotify_mcp_cache.json.

3. Добавление в MCP-клиент

Запуск локально (рекомендуется)

git clone https://github.com/verIdyia/spotify-mcp.git

Добавьте в свою конфигурацию MCP (Claude Desktop, Cursor и т.д.):

{
  "mcpServers": {
    "spotify": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/spotify-mcp",
        "run",
        "spotify-mcp"
      ],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id",
        "SPOTIFY_CLIENT_SECRET": "your_client_secret",
        "SPOTIFY_REDIRECT_URI": "http://127.0.0.1:8080/callback"
      }
    }
  }
}

Запуск с помощью uvx

{
  "mcpServers": {
    "spotify": {
      "command": "uvx",
      "args": [
        "--python", "3.12",
        "--from", "git+https://github.com/verIdyia/spotify-mcp",
        "spotify-mcp"
      ],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id",
        "SPOTIFY_CLIENT_SECRET": "your_client_secret",
        "SPOTIFY_REDIRECT_URI": "http://127.0.0.1:8080/callback"
      }
    }
  }
}

Переменные окружения

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

1. Первый запуск: Выполните spotify-mcp --auth для завершения процесса OAuth перед использованием с MCP-клиентом

2. Токен истек: Токены обновляются автоматически. Если проблемы сохраняются, повторно запустите --auth

3. Нет активного устройства: Убедитесь, что Spotify открыт и воспроизводит музыку хотя бы на одном устройстве

4. Убедитесь, что uv обновлен — рекомендуется версия >=0.54

Отладка

Запустите инспектор MCP:

npx @modelcontextprotocol/inspector uv --directory /path/to/spotify-mcp run spotify-mcp

Сводка изменений Spotify API от февраля 2026 года

Авторы

• Оригинальный проект: varunneal/spotify-mcp от Varun Srivastava (лицензия MIT)

• Оригинальные участники: @jamiew, @davidpadbury, @manncodes, @hyuma7, @aanurraj, @JJGO и другие

• Создано с помощью: httpx, MCP SDK

• Поддерживается с помощью: Claude Code (Anthropic)

Лицензия

Лицензия MIT — подробности см. в LICENSE.