spotify-mcp

Spotify Web API'yı MCP olarak Hermes'e bağlayan sunucu. Computer use / UI otomasyonu yok — her şey resmi Spotify Web API ile. Windows, macOS ve Linux'ta çalışır; hesaptaki hangi cihaz aktifse (desktop, telefon, web) onu kontrol eder.

Özellikler

• ▶️ Şarkı/albüm/sanatçı/playlist ara & çal
• ⏸️ Duraklat / devam et / ileri / geri
• 🔊 Ses seviyesi (0-100)
• ⏭️ Sıraya ekle (queue)
• 📱 Aktif cihazları listele, çalan şarkıyı göster

Kurulum

1. Spotify Developer App oluştur

1. https://developer.spotify.com/dashboard adresine gir → Create app
2. App name/description doldur, Redirect URI olarak şunu ekle:

   http://127.0.0.1:8890/callback
   

3. Client ID'yi (ve varsa Client Secret'ı) kopyala.

2. Config yaz

mkdir -p ~/.spotify-mcp

~/.spotify-mcp/config.json:

{
  "clientId": "SENIN_CLIENT_ID",
  "clientSecret": "SENIN_CLIENT_SECRET"
}

3. OAuth (bir kere)

node auth.js

Tarayıcı açılır, Spotify'a girip Agree'e basarsın, token ~/.spotify-mcp/tokens.json'a kaydedilir. Refresh token otomatik yenilenir.

4. Hermes'e ekle

printf 'Y\n' | hermes mcp add spotify --command node --args C:/Users/<user>/Documents/GitHub/spotify-mcp/server.js
hermes mcp ls
hermes mcp test spotify

MCP tool'ları yeni oturumlarda yüklenir — ekledikten sonra yeni bir sohbet başlat.

Tool'lar

Tool	Açıklama
spotify_play_track(query[, device])	Şarkı ara & hemen çal
spotify_play_artist(name[, device])	Sanatçı çal
spotify_play_album(query[, device])	Albüm çal
spotify_play_playlist(name[, device])	Playlist çal
spotify_play_uri(uri[, device])	Direkt spotify: URI çal
spotify_queue_track(query)	Sıraya ekle
spotify_pause / spotify_resume([device])	Duraklat / devam
spotify_next / spotify_previous	İleri / geri
spotify_set_volume(percent[, device])	Ses 0-100
spotify_playback_state	Ne çalıyor, hangi cihazda
spotify_list_devices	Aktif cihazlar (id'leriyle)
spotify_search(query, type)	Arama
spotify_auth_status	Auth durumu

device = cihaz adı. Önce tam eşleşme aranır (örn. "FURKAN" → Windows PC), tam eşleşme yoksa alt dize (örn. "Macbook" → "Furkan Macbook Air"). Dikkat: "FURKAN" aynı zamanda "Furkan Macbook Air"in alt dizesi — bu yüzden tam eşleşme önceliklidir! Verilmezse aktif cihazda çalar. Cihaz değişiminde aktif cihaz önce pause edilir (~7sn oturum bırakma süresi), sonra hedefe play edilir.

Notlar

• Playback kontrolü (play/pause/skip/volume) Premium hesap gerektirir (Spotify kuralı). Arama ve auth her hesapta çalışır.
• Playback, hesabında aktif olan cihaza gider. Cihaz yoksa: Spotify'ı aç, bir şarkı başlat, sonra tekrar dene.
• Sıfır npm bağımlılığı — Node >= 18 yeterli.

Test (probe)

printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"1.0"}}}\n' | node server.js