controlling-spotify

Spotifyを操作する

Spotify MCP サーバーを使用して、Spotifyの再生を操作したり、音楽を検索したり、プレイリストを管理したりできます。ユーザーアカウントに完全にアクセスできます。

使用するタイミング

ユーザーから次のリクエストがあった場合に、このスキルを呼び出します。

• Spotifyで音楽を再生、一時停止、またはスキップする
• 曲、アルバム、アーティスト、またはプレイリストを検索する
• プレイリストを作成または変更する
• 現在再生中のトラックまたは再生状況を確認する
• Spotifyライブラリ（保存したトラック、アルバム）を管理する
• 曲またはアルバムをキューに追加する

前提条件

重要：このスキルには、ユーザーが提供する認証情報が必要です。ユーザーは一度だけセットアップを完了する必要があります。

ユーザーによる一度限りのセットアップ

1. Spotify Developerアプリケーションを作成する

   • https://developer.spotify.com/dashboard/ にアクセスします
   • アプリを作成し、Client IDとClient Secretを控えます
   • リダイレクトURIを追加します：http://127.0.0.1:8888/callback

2. リフレッシュトークンを取得する

   • ユーザーはヘルパースクリプトをローカルで実行する必要があります（references/setup-guide.mdを参照）
   • スクリプトはOAuthコードを長期間有効なリフレッシュトークンに交換します
   • リフレッシュトークンはスキルの設定に認証情報として保存されます

3. 認証情報を設定する

   • このスキルに次の3つの認証情報を追加します。
     • SPOTIFY_CLIENT_ID：Spotify Developer Dashboardから取得
     • SPOTIFY_CLIENT_SECRET：Spotify Developer Dashboardから取得
     • SPOTIFY_REFRESH_TOKEN：ヘルパースクリプトの出力から取得

   別の方法：認証情報はProject Knowledgeファイルからも提供できます。ファイルに、上記のキーを含む.env形式のブロックがあることを確認してください。

これらの認証情報がないと、このスキルは機能しません。 認証情報がない場合は、references/setup-guide.mdに記載されたセットアップ手順をユーザーに案内してください。

MCP サーバーのインストール

Spotify MCP サーバーをコンピューティング環境にインストールする必要があります。サーバーのクローン作成、パッチ適用、ビルドを処理する付属のインストールスクリプトを使用してください。

# Run the installation script
bash scripts/install-mcp-server.sh

MCP サーバーの設定

Spotify MCP サーバーに接続するようにMCPクライアントを設定します。Project Knowledgeからの認証情報をサポートするロジックに注意してください。

from mcp import Client
import asyncio
import re

# 1. Try to get credentials from skill configuration
env_vars = {
    "SPOTIFY_CLIENT_ID": credentials.get("SPOTIFY_CLIENT_ID"),
    "SPOTIFY_CLIENT_SECRET": credentials.get("SPOTIFY_CLIENT_SECRET"),
    "SPOTIFY_REFRESH_TOKEN": credentials.get("SPOTIFY_REFRESH_TOKEN")
}

# 2. If missing, look in Project Knowledge / Context for .env style block
if not all(env_vars.values()):
    # Heuristic: Scan context/files for VAR=VALUE patterns
    # (Pseudo-code: Implement based on available context access)
    pass

# Server configuration
mcp_config = {
    "command": "node",
    "args": ["/home/claude/spotify-mcp-server/build/index.js"],
    "env": env_vars
}

# Initialize client
async def initialize_spotify_mcp():
    client = Client()
    await client.connect_stdio(
        mcp_config["command"],
        mcp_config["args"],
        mcp_config["env"]
    )
    return client

利用可能なツール

読み取り操作

1. searchSpotify - トラック、アルバム、アーティスト、またはプレイリストを検索します

   result = await client.call_tool("searchSpotify", {
       "query": "bohemian rhapsody",
       "type": "track",
       "limit": 10
   })
   

2. getNowPlaying - 現在再生中のトラック情報を取得します

   result = await client.call_tool("getNowPlaying", {})
   

3. getMyPlaylists - ユーザーのプレイリストを一覧表示します

   result = await client.call_tool("getMyPlaylists", {
       "limit": 20,
       "offset": 0
   })
   

4. getPlaylistTracks - プレイリストのトラックを取得します

   result = await client.call_tool("getPlaylistTracks", {
       "playlistId": "37i9dQZEVXcJZyENOWUFo7"
   })
   

5. getRecentlyPlayed - 最近再生したトラックを取得します

   result = await client.call_tool("getRecentlyPlayed", {
       "limit": 10
   })
   

6. getUsersSavedTracks - ユーザーのお気に入りの曲を取得します

   result = await client.call_tool("getUsersSavedTracks", {
       "limit": 50,
       "offset": 0
   })
   

再生コントロール

1. playMusic - トラック／アルバム／アーティスト／プレイリストの再生を開始します

   # Play by URI
   result = await client.call_tool("playMusic", {
       "uri": "spotify:track:6rqhFgbbKwnb9MLmUQDhG6"
   })
   
   # Or by type and ID
   result = await client.call_tool("playMusic", {
       "type": "track",
       "id": "6rqhFgbbKwnb9MLmUQDhG6"
   })
   

2. pausePlayback - 現在の再生を一時停止します

   result = await client.call_tool("pausePlayback", {})
   

3. skipToNext - 次のトラックにスキップします

   result = await client.call_tool("skipToNext", {})
   

4. skipToPrevious - 前のトラックにスキップします

   result = await client.call_tool("skipToPrevious", {})
   

5. addToQueue - トラック／アルバムを再生キューに追加します

   result = await client.call_tool("addToQueue", {
       "uri": "spotify:track:6rqhFgbbKwnb9MLmUQDhG6"
   })
   

プレイリスト管理

1. createPlaylist - 新しいプレイリストを作成します

   result = await client.call_tool("createPlaylist", {
       "name": "My Workout Mix",
       "description": "High energy tracks",
       "public": False
   })
   

2. addTracksToPlaylist - 既存のプレイリストにトラックを追加します

   result = await client.call_tool("addTracksToPlaylist", {
       "playlistId": "3cEYpjA9oz9GiPac4AsH4n",
       "trackUris": [
           "spotify:track:4iV5W9uYEdYUVa79Axb7Rh",
           "spotify:track:6rqhFgbbKwnb9MLmUQDhG6"
       ]
   })
   

アルバム操作

1. getAlbums - アルバムの詳細を取得します

   result = await client.call_tool("getAlbums", {
       "albumIds": ["4aawyAB9vmqN3uQ7FjRGTy"]
   })
   

2. getAlbumTracks - アルバムのトラックを取得します

   result = await client.call_tool("getAlbumTracks", {
       "albumId": "4aawyAB9vmqN3uQ7FjRGTy"
   })
   

3. saveOrRemoveAlbumForUser - アルバムを保存または削除します

   result = await client.call_tool("saveOrRemoveAlbumForUser", {
       "albumIds": ["4aawyAB9vmqN3uQ7FjRGTy"],
       "action": "save"
   })
   

ワークフローの例

例1：ユーザーのお気に入りの曲を再生する

# 1. Search for the song
search_result = await client.call_tool("searchSpotify", {
    "query": "user's favorite song name",
    "type": "track",
    "limit": 1
})

# 2. Extract track URI from results
track_uri = search_result["tracks"][0]["uri"]

# 3. Play the track
await client.call_tool("playMusic", {
    "uri": track_uri
})

例2：ジャンルからプレイリストを作成する

# 1. Search for tracks in genre
search_result = await client.call_tool("searchSpotify", {
    "query": "genre:rock year:2020-2024",
    "type": "track",
    "limit": 20
})

# 2. Create new playlist
playlist_result = await client.call_tool("createPlaylist", {
    "name": "Modern Rock Mix",
    "description": "Recent rock tracks",
    "public": False
})

# 3. Extract track URIs
track_uris = [track["uri"] for track in search_result["tracks"]]

# 4. Add tracks to playlist
await client.call_tool("addTracksToPlaylist", {
    "playlistId": playlist_result["id"],
    "trackUris": track_uris
})

例3：再生中の曲を表示する

# Get current playback state
now_playing = await client.call_tool("getNowPlaying", {})

# Format and display
print(f"Now Playing: {now_playing['track']['name']}")
print(f"Artist: {now_playing['track']['artists'][0]['name']}")
print(f"Album: {now_playing['track']['album']['name']}")
print(f"Progress: {now_playing['progress_ms']} / {now_playing['duration_ms']} ms")

重要な注意事項

Spotify Premiumが必要

再生コントロール操作（再生、一時停止、スキップ、キュー）にはSpotify Premiumが必要です。読み取り操作（検索、プレイリストの取得、トラックの表示）は無料アカウントでも利用できます。

アクティブなデバイスが必要

再生コマンドを機能させるには、ユーザーがデバイスを利用可能な状態で、Spotifyのセッション（ウェブプレーヤー、デスクトップアプリ、モバイルアプリ）をアクティブにしている必要があります。アクティブなデバイスがない場合、再生コマンドは失敗します。

レート制限

Spotify APIにはレート制限があります（通常、1分あたり180リクエスト）。一括操作では、適切な待機時間を設けるか、バッチ処理を実装してください。

トークンのセキュリティ

• リフレッシュトークンを使うと、ユーザーの Spotify アカウントに完全にアクセスできます
• リフレッシュトークンを決してログに記録したり、公開したりしないでください
• パスワードと同じレベルのセキュリティで取り扱ってください
• ユーザーは https://www.spotify.com/account/apps/ からトークンを取り消せます

URI 形式

Spotify では、次の形式の URI を使用します。

• トラック：spotify:track:ID
• アルバム：spotify:album:ID
• アーティスト：spotify:artist:ID
• プレイリスト：spotify:playlist:ID

ほとんどのツールでは、URI または個別の type と id パラメーターを使用できます。

トラブルシューティング

「Spotify configuration not found」

原因：環境変数が設定されていません

解決策：認証情報が正しく設定されていることを確認してください。

import os
print(os.getenv("SPOTIFY_CLIENT_ID"))  # Should not be None
print(os.getenv("SPOTIFY_CLIENT_SECRET"))  # Should not be None
print(os.getenv("SPOTIFY_REFRESH_TOKEN"))  # Should not be None

「No active device」

原因：Spotify クライアントが現在起動またはアクティブになっていません

解決策：ユーザーに次の操作を案内してください。

1. 任意のデバイス（ウェブ、デスクトップ、モバイル）で Spotify を開く
2. 再生を開始する（一時停止はすぐに行ってもかまいません）
3. 再生コマンドをもう一度試す

「Premium required」

原因：ユーザーが Spotify Free アカウントを使用しています

解決策：再生の制御には Spotify Premium が必要です。無料アカウントで利用できるのは、検索と読み取り操作のみです。

MCP サーバーが起動しない

原因：依存関係が不足しているか、インストールが正しくありません

解決策：

# Re-run installation script
bash scripts/install-mcp-server.sh

ベストプラクティス

1. 再生する前に必ず検索する - URI を決めつけず、まずコンテンツを検索してください
2. 再生状態を確認する - getNowPlaying を使ってデバイスが利用可能か確認してください
3. エラーを適切に処理する - 操作が失敗したときは、役立つメッセージを表示してください
4. 操作をまとめる - 複数のトラックを追加する場合は、配列を使って一度に呼び出してください
5. レート制限を守る - 一括操作では遅延を加えてください

参考資料

• セットアップガイド：references/setup-guide.md
• API ドキュメント：https://developer.spotify.com/documentation/web-api/
• MCP 仕様：https://modelcontextprotocol.io/

セキュリティ

このスキルでは機密性の高い認証情報が必要です。次の点を徹底してください。

• 認証情報はスキルの設定に安全に保存する
• ユーザーへの応答で認証情報を決して公開しない
• 認証情報を決してログに記録しない
• ユーザーがいつでもアクセスを取り消せることを理解しているか確認する

セキュリティのベストプラクティスについて詳しくは、references/setup-guide.md を参照してください。