MCP Claude Spotify

MCP Клод Spotify

Функции

• Аутентификация Spotify
• Поиск треков, альбомов, исполнителей и плейлистов
• Управление воспроизведением (воспроизведение, пауза, следующий, предыдущий)
• Создавайте и управляйте плейлистами
• Получите персонализированные рекомендации
• Доступ к самым популярным трекам пользователя за разные периоды времени

Демо

Требования

• Node.js 16 или выше
• Аккаунт Spotify
• Клод Десктоп
• Учетные данные API Spotify (идентификатор клиента и секретный код клиента)

Установка

Установка через Smithery

Чтобы автоматически установить MCP Claude Spotify для Claude Desktop через Smithery :

Установка вручную

1. Клонируйте или загрузите этот репозиторий:

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

3. Соберите проект (если вы хотите изменить исходный код):

Репозиторий уже содержит предварительно собранные файлы в каталоге build , поэтому вы можете пропустить шаг 3, если не планируете изменять исходный код.

Настройка учетных данных Spotify

Чтобы использовать этот MCP, вам необходимо получить учетные данные Spotify API:

1. Перейти к панели инструментов разработчика Spotify
2. Войдите в систему, используя свою учетную запись Spotify.
3. Нажмите «Создать приложение».
4. Заполните информацию о вашем приложении:
   • Название приложения: «MCP Claude Spotify» (или любое другое по вашему желанию)
   • Описание приложения: «Интеграция Spotify для Claude Desktop»
   • Веб-сайт: Вы можете оставить это поле пустым или ввести любой URL-адрес.
   • URI перенаправления: Важно — добавьте http://127.0.0.1:8888/callback
5. Примите условия и положения и нажмите «Создать»
6. На панели управления вашего приложения вы увидите «Идентификатор клиента».
7. Нажмите «Показать секрет клиента», чтобы раскрыть свой «секрет клиента».

Сохраните эти учетные данные, так как они понадобятся вам для настройки.

Запуск сервера MCP

Существует два способа запуска сервера MCP:

Вариант 1: запуск вручную (рекомендуется для первоначальной настройки и устранения неполадок)

1. Откройте терминал или командную строку.
2. Перейдите в каталог проекта.
3. Запустите сервер напрямую:

Держите это окно терминала открытым при использовании Claude Desktop. Сервер будет работать, пока вы не закроете терминал.

Вариант 2: Автоматический запуск с помощью Claude Desktop (рекомендуется для регулярного использования)

Claude Desktop может автоматически запускать сервер MCP при необходимости. Чтобы настроить это:

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

Файл конфигурации Claude Desktop находится по адресу:

• macOS : ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows : %APPDATA%\Claude\claude_desktop_config.json

Отредактируйте этот файл, чтобы добавить конфигурацию Spotify MCP. Если файл не существует, создайте его:

Важно : Заменить:

• ABSOLUTE_PATH_TO_DIRECTORY с полным абсолютным путем, по которому вы установили MCP
  • Пример для macOS/Linux: /Users/username/mcp-claude-spotify
  • Пример для Windows: C:\\Users\\username\\mcp-claude-spotify
• your_client_id_here на идентификатор клиента, полученный от Spotify
• your_client_secret_here с Client Secret, который вы получили от Spotify

Если у вас уже настроены другие MCP, просто добавьте раздел «spotify» внутри объекта «mcpServers».

Настройка скриптов автозапуска (необязательно)

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

1. Создайте в каталоге проекта файл с именем start-spotify-mcp.bat со следующим содержимым:

2. Создайте ярлык для этого BAT-файла
3. Нажмите Win+R , введите shell:startup и нажмите Enter.
4. Переместите ярлык в эту папку, чтобы он запускался вместе с Windows.
5. Создайте файл с именем com.spotify.mcp.plist в ~/Library/LaunchAgents/ со следующим содержимым:

2. Замените путь и учетные данные на ваши фактические значения.
3. Загрузите агент с помощью: launchctl load ~/Library/LaunchAgents/com.spotify.mcp.plist
4. Создайте файл с именем spotify-mcp.service в ~/.config/systemd/user/ (создайте каталог, если он не существует):

2. Замените путь и учетные данные на ваши фактические значения.
3. Включите и запустите службу:

4. Проверить статус можно с помощью:

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

1. Перезапустите Claude Desktop после изменения конфигурации.
2. В Claude используйте команду auth-spotify для запуска процесса аутентификации.
3. Откроется окно браузера для авторизации приложения.
4. Войдите в свою учетную запись Spotify и авторизуйте приложение.
5. Важно : после успешной аутентификации перезапустите Claude Desktop, чтобы правильно инициализировать реестр инструментов MCP и кэш токенов сеанса WebSocket.
6. После перезапуска все инструменты Spotify MCP будут правильно зарегистрированы и доступны для использования.

Сервер MCP работает как дочерний процесс, управляемый Claude Desktop. Когда Claude запущен, он автоматически запускает и управляет процессом сервера Node.js на основе конфигурации в claude_desktop_config.json .

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

auth-spotify

Запускает процесс аутентификации Spotify.

поиск-spotify

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

Параметры:

• query : Поиск текста
• type : Тип поиска (трек, альбом, исполнитель, плейлист)
• limit : количество результатов (1-50)

плей-трек

Воспроизводит определенный трек.

Параметры:

• trackId : идентификатор трека Spotify
• deviceId : (Необязательно) идентификатор устройства Spotify для воспроизведения

получить-текущее-воспроизведение

Получает информацию о текущем воспроизведении.

пауза-воспроизведение

Приостанавливает воспроизведение.

следующий трек

Переход к следующему треку.

предыдущий-трек

Возврат к предыдущему треку.

получить-пользовательские-плейлисты

Получает плейлисты пользователя.

создать-плейлист

Создает новый плейлист.

Параметры:

• name : Имя плейлиста
• description : (Необязательно) Описание
• public : (Необязательно) Является ли он публичным или частным

добавить-треки-в-плейлист

Добавляет треки в плейлист.

Параметры:

• playlistId : Идентификатор плейлиста
• trackIds : Массив идентификаторов треков

получить-рекомендации

Получает рекомендации на основе семян.

Параметры:

• seedTracks : (Необязательно) Массив идентификаторов треков
• seedArtists : (Необязательно) Массив идентификаторов исполнителей
• seedGenres : (Необязательно) Массив жанров
• limit : (Необязательно) Количество рекомендаций (1-100)

получить-топ-треки

Получает самые прослушиваемые треки пользователя за указанный период времени.

Параметры:

• limit : (Необязательно) Количество возвращаемых треков (1-50, по умолчанию: 20)
• offset : (Необязательно) Индекс первой возвращаемой дорожки (по умолчанию: 0)
• time_range : (Необязательно) Временной интервал для расчета сродства:
  • short_term : Примерно последние 4 недели
  • medium_term : приблизительно последние 6 месяцев (по умолчанию)
  • long_term : Данные за несколько лет

Поиск неисправностей

Ошибка «Сервер отключен»

Если вы видите ошибку «MCP Spotify: Server disconnected» в Claude Desktop:

1. Убедитесь, что сервер работает :
   • Откройте терминал и вручную запустите node build/index.js из каталога проекта.
   • Если сервер запустится успешно, используйте Claude, оставив этот терминал открытым.
2. Проверьте вашу конфигурацию :
   • Убедитесь, что абсолютный путь в claude_desktop_config.json правильный для вашей системы.
   • Дважды проверьте, что вы использовали двойные обратные косые черты ( \\ ) для путей Windows.
   • Убедитесь, что вы используете полный путь от корня вашей файловой системы.
3. Попробуйте опцию автозапуска :
   • Настройте скрипт автозапуска для вашей операционной системы, как описано в разделе «Настройка скриптов автозапуска».
   • Это гарантирует, что сервер всегда будет работать, когда вам это нужно.

Браузер не открывается автоматически

Если браузер не открывается автоматически во время аутентификации, вручную перейдите по адресу: http://127.0.0.1:8888/login

Ошибка аутентификации

Убедитесь, что вы правильно настроили URI перенаправления в панели инструментов разработчика Spotify: http://127.0.0.1:8888/callback

Ошибка запуска сервера

Убедитесь, что:

• Переменные среды правильно настроены в файле claude_desktop_config.json или в скрипте запуска.
• Node.js установлен и совместим (v16+)
• Необходимые порты (8888) доступны и не заблокированы брандмауэром.
• У вас есть разрешение на запуск скрипта в указанном месте

Инструменты не отображаются в Claude

Если инструменты Spotify не отображаются в Claude после аутентификации:

• Убедитесь, что вы перезапустили Claude Desktop после успешной аутентификации.
• Проверьте журналы Claude Desktop на наличие ошибок связи MCP.
• Убедитесь, что процесс сервера MCP запущен (запустите его вручную для подтверждения)
• Убедитесь, что сервер MCP правильно зарегистрирован в реестре Claude Desktop MCP.

Проверка работоспособности сервера

Чтобы проверить, работает ли сервер:

• Windows : Откройте диспетчер задач, перейдите на вкладку «Подробности» и найдите «node.exe».
• macOS/Linux : Откройте терминал и выполните команду ps aux | grep node

Если вы не видите работающего сервера, запустите его вручную или воспользуйтесь методом автоматического запуска.

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

Этот проект включает автоматизированные тесты для обеспечения качества и функциональности кода. Тестовый набор использует Jest с поддержкой TypeScript и охватывает:

• Проверка схемы Zod — проверяет все входные схемы, правильно ли проверяются данные
• Взаимодействие API Spotify — тесты обработки запросов API и обработки ошибок
• Функциональность сервера MCP — обеспечивает правильную регистрацию и выполнение инструментов

Проведение тестов

Сначала убедитесь, что установлены все зависимости разработки:

Чтобы запустить все тесты:

Чтобы запустить определенный тестовый файл:

Если у вас возникли проблемы с модулями ESM, убедитесь, что вы используете Node.js v16 или выше и что переменная среды NODE_OPTIONS включает флаг --experimental-vm-modules , настроенный в package.json.

Структура теста

• tests/schemas.test.ts : Тесты для схем проверки входных данных
• tests/spotify-api.test.ts : Тесты для взаимодействия API Spotify
• tests/server.test.ts : Тесты функциональности сервера MCP

Добавление новых тестов

При добавлении новых функций, пожалуйста, включайте соответствующие тесты:

1. Для новых схем добавьте проверочные тесты в schemas.test.ts
2. Для функций API Spotify добавьте тесты в spotify-api.test.ts
3. Для инструментов MCP добавьте тесты в server.test.ts

Все тесты должны быть написаны с использованием Jest и формата модуля ESM с использованием TypeScript.

Заметки о безопасности

• Никогда не сообщайте свой идентификатор клиента и секретный код клиента.
• Токен доступа теперь хранится в домашнем каталоге пользователя по адресу ~/.spotify-mcp/tokens.json что обеспечивает сохранение между сеансами и несколькими экземплярами.
• Пользовательские данные не хранятся на диске.

Отзыв доступа к приложению

В целях безопасности вы можете отозвать доступ приложения к вашей учетной записи Spotify в следующих случаях:

• Вы больше не используете эту интеграцию
• Вы подозреваете несанкционированный доступ
• Вы устраняете неполадки аутентификации

Чтобы отозвать доступ:

1. Перейдите на страницу вашего аккаунта Spotify.
2. Перейдите в меню «Приложения».
3. Найдите «MCP Claude Spotify» (или название, которое вы выбрали для своего приложения)
4. Нажмите «УДАЛИТЬ ДОСТУП»

Это немедленно аннулирует все токены доступа и обновления. В следующий раз, когда вы используете команду auth-spotify , вам нужно будет снова авторизовать приложение.

Внося вклад

Вклады приветствуются! Вот несколько рекомендаций, которым нужно следовать:

Рабочий процесс разработки

1. Форк репозитория
2. Создайте ветку функций ( git checkout -b feature/amazing-feature )
3. Внесите изменения
4. Запустите тесты, чтобы убедиться, что они пройдены ( npm test )
5. Зафиксируйте свои изменения ( git commit -m 'Add some amazing feature' )
6. Отправить в ветку ( git push origin feature/amazing-feature )
7. Открыть запрос на извлечение

Правила оформления кода

Этот проект следует следующим стандартам кодирования:

• Используйте TypeScript со строгой проверкой типов
• Соблюдайте формат модуля ESM
• Используйте 2 пробела для отступа.
• Используйте camelCase для переменных и функций
• Используйте PascalCase для классов и интерфейсов
• Функции документа с комментариями JSDoc
• Длина строки не должна превышать 100 символов.

Структура проекта

Проект имеет следующую структуру:

Процесс запроса на извлечение

1. Убедитесь, что ваш код соответствует рекомендациям по стилю.
2. При необходимости обновите документацию.
3. Добавить тесты для новых функций
4. Убедитесь, что все тесты пройдены
5. Ваш PR будет рассмотрен специалистами по поддержке

Ссылки по теме

• Модель контекстного протокола
• Документация по веб-API Spotify
• Клод Десктоп
• Серия МКП

Лицензия

Данный проект лицензирован в соответствии с Mozilla Public License 2.0 — подробности см. в файле LICENSE .