mcpField
S
spotify

spotify

github.com/nousresearchその他258.1k75 回インストール今日更新
リポジトリ

spotify について

spotifyは、7つのツールを通じてSpotifyを操作するHermesユーザー向けのスキルです。再生、検索、プレイリスト、デバイス、ライブラリの操作手順とエラー時の対応をまとめています。

主な機能

  1. 01再生操作とデバイス切り替え
  2. 02曲やアルバムの検索
  3. 03キューとプレイリストの管理
  4. 04ライブラリ項目の確認と保存

活用シーン

  1. 01音楽の再生、一時停止、スキップ
  2. 02曲を探してプレイリストに追加
  3. 03再生中の曲の確認
  4. 04曲やアルバムをライブラリに保存

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/nousresearch/hermes-agent --skill spotify

インストール後、Claude Code で/spotifyを入力して読み込まれたか確認します。

詳細

Spotify

Hermes Spotify ツールセット（7 つのツール）を使って、ユーザーの Spotify アカウントを操作します。セットアップガイド：https://hermes-agent.nousresearch.com/docs/user-guide/features/spotify

このスキルを使う場面

ユーザーが「X を再生して」「一時停止して」「スキップして」「X をキューに追加して」「何が再生中？」「X を検索して」「X のプレイリストに追加して」「プレイリストを作成して」「これをライブラリに保存して」などと言った場合です。

7 つのツール

  • spotify_playback — 再生、一時停止、次へ、前へ、シーク、リピート設定、シャッフル設定、音量設定、状態取得、再生中の項目の取得、最近再生した項目の取得
  • spotify_devices — 一覧表示、転送
  • spotify_queue — 取得、追加
  • spotify_search — カタログを検索
  • spotify_playlists — 一覧表示、取得、作成、アイテムの追加、アイテムの削除、詳細の更新
  • spotify_albums — 取得、トラック
  • spotify_library — kind: "tracks"|"albums" を指定して一覧表示／保存／削除

再生状態を変更する操作には Spotify Premium が必要です。検索／ライブラリ／プレイリストの操作は Free でも利用できます。

基本的なパターン（ツール呼び出しを最小限にする）

「<アーティスト／トラック／アルバム>を再生して」

検索を 1 回行い、その URI を使って再生します。ユーザーが選択肢を求めていない限り、検索結果を順番に確認して説明しないでください。

spotify_search({"query": "miles davis kind of blue", "types": ["album"], "limit": 1})
→ got album URI spotify:album:1weenld61qoidwYuZ1GESA
spotify_playback({"action": "play", "context_uri": "spotify:album:1weenld61qoidwYuZ1GESA"})

「<アーティスト>の曲を何か再生して」のように特定の曲を指定していない場合は、types: ["artist"] を優先し、アーティストのコンテキスト URI を使って再生します。Spotify がスマートシャッフルを処理します。ユーザーが「その曲」や「あのトラック」と言った場合は、types: ["track"] で検索し、uris: [track_uri] を指定して再生します。

「何が再生中？」／「何を聴いてる？」

1 回だけ呼び出します。get_currently_playing の後に get_state を続けて呼び出さないでください。

spotify_playback({"action": "get_currently_playing"})

204／空の応答（is_playing: false）が返された場合は、何も再生されていないとユーザーに伝えます。再試行しないでください。

「一時停止して」／「スキップして」／「音量を 50 にして」

事前に状態を確認する必要はありません。直接操作します。

spotify_playback({"action": "pause"})
spotify_playback({"action": "next"})
spotify_playback({"action": "set_volume", "volume_percent": 50})
「自分の<プレイリスト名>プレイリストに追加して」
  1. spotify_playlists list を使い、プレイリスト名からプレイリスト ID を探します
  2. トラック URI を取得します（再生中の項目から取得するか、検索します）
  3. プレイリスト ID と URI を指定して spotify_playlists add_items を実行します
spotify_playlists({"action": "list"})
→ found "Late Night Jazz" = 37i9dQZF1DX4wta20PHgwo
spotify_playback({"action": "get_currently_playing"})
→ current track uri = spotify:track:0DiWol3AO6WpXZgp0goxAV
spotify_playlists({"action": "add_items",
                   "playlist_id": "37i9dQZF1DX4wta20PHgwo",
                   "uris": ["spotify:track:0DiWol3AO6WpXZgp0goxAV"]})
「最後に再生した 3 曲でプレイリストを作成して」
spotify_playback({"action": "recently_played", "limit": 3})
spotify_playlists({"action": "create", "name": "Focus 2026"})
→ got playlist_id back in response
spotify_playlists({"action": "add_items", "playlist_id": <id>, "uris": [<3 uris>]})
「保存して」／「保存を解除して」／「これは保存済み？」

適切な kind を指定して spotify_library を使います。

spotify_library({"kind": "tracks", "action": "save", "uris": ["spotify:track:..."]})
spotify_library({"kind": "albums", "action": "list", "limit": 50})
「再生を自分の<デバイス>に転送して」
spotify_devices({"action": "list"})
→ pick the device_id by matching name/type
spotify_devices({"action": "transfer", "device_id": "<id>", "play": true})

重大な失敗パターン

再生操作で 403 Forbidden — No active device found が発生した場合、Spotify はどこでも起動していません。ユーザーに次のように伝えてください：「まずスマートフォン／デスクトップ／ウェブプレーヤーで Spotify を開き、任意のトラックを数秒間再生してから、もう一度お試しください。」やみくもにツール呼び出しを再試行しないでください。同じ理由で失敗します。spotify_devices list を呼び出して確認することもできます。リストが空の場合、アクティブなデバイスはありません。

403 Forbidden — Premium required は、ユーザーが Free を利用していて、再生状態を変更しようとしたことを意味します。再試行せず、この操作には Premium が必要だと伝えてください。読み取り操作（検索、プレイリスト、ライブラリ、get_state）は引き続き利用できます。

**get_currently_playing の 204 No Content はエラーではありません。何も再生されていないことを意味します。ツールは is_playing: false を返します。そのままユーザーに伝えてください。

429 Too Many Requests はレート制限です。待ってから 1 回だけ再試行します。それでも発生する場合は、ループしています。停止してください。

再試行後に 401 Unauthorized が発生した場合 — リフレッシュトークンが取り消されています。もう一度 hermes auth spotify を実行するようユーザーに伝えてください。

URI と ID の形式

Spotify では、相互に変換可能な 3 種類の ID 形式が使われます。ツールはいずれの形式も受け付け、正規化します。

  • URI：spotify:track:0DiWol3AO6WpXZgp0goxAV（推奨）
  • URL：https://open.spotify.com/track/0DiWol3AO6WpXZgp0goxAV
  • ID のみ：0DiWol3AO6WpXZgp0goxAV

迷った場合は、完全な URI を使ってください。検索結果では uri フィールドに URI が返されます。それをそのまま渡してください。

エンティティの種類：track、album、artist、playlist、show、episode。操作に適した種類を使ってください。context_uri を指定する spotify_playback.play にはアルバム／プレイリスト／アーティストを指定し、uris にはトラック URI の配列を指定します。

してはいけないこと

  • 操作のたびに get_state を呼び出さないでください。 Spotify は事前確認なしで再生／一時停止／スキップを受け付けます。ユーザーから「何が再生中ですか」と尋ねられた場合、またはデバイスやトラックについて判断する必要がある場合にのみ、状態を確認してください。
  • 求められていない限り、検索結果を説明しないでください。 ユーザーが「Xを再生して」と言った場合は、検索して最初に表示された URI を取得し、再生してください。間違っていれば、ユーザーは再生を聞いて気づきます。
  • 403 Premium required または 403 No active device が返された場合は、再試行しないでください。 これらは、ユーザーが操作するまで解消されません。
  • プレイリストを名前で探すために spotify_search を使わないでください — これは Spotify の公開カタログを検索します。ユーザーのプレイリストは spotify_playlists list から取得します。
  • spotify_library では kind: "tracks" とアルバム URI を組み合わせないでください（その逆も同様です）。このツールは ID を正規化しますが、API エンドポイントは異なります。

コメント

Markdown 対応