Spotify MCP

🚀 Spotify Playlist MCP Server

自然言語を使用して即座にプレイリストを作成するためのモデルコンテキストプロトコルサーバーです。いくつかの類似性判定方法を用いて、類似するトラックを見つけることもできます。

このプロジェクトは、以下の2つの個人的なニーズを満たすために開発されました。

1. 自然言語といくつかの類似性指標を使用してプレイリストを作成すること。理想的には一時的なプレイリストを作成したいところですが、現状はそうなっていません。
2. 新しいClaudeスキルを試して、AI支援コーディングにどれだけ役立つかを確認すること。結果は、トークンを大量に消費するかもしれませんが、非常にうまく機能します。

警告: このプロジェクトはまだ実際の環境で十分にテストされておらず、評価もまだ書かれていません。

✨ 主な機能

コアプレイリスト管理

• Spotifyプレイリストの作成と管理
• Spotifyのカタログ全体でトラックを検索
• トラックの詳細と推薦を取得
• ユーザーのプレイリストとプレイリストの内容を閲覧

高度な類似性エンジン

• オーディオ特徴分析: 音響性、ダンス性、エネルギー、テンポ、バレンスなどを抽出して分析
• 複数の類似性アルゴリズム: 8種類の異なる戦略（ユークリッド距離、コサイン類似度、重み付き、マンハッタン距離、エネルギーマッチ、ムードマッチ、リズムマッチ、ジャンルマッチ）から選択
• ジャンルベースのマッチング: プレイリストまたはコレクション内で、アーティストのジャンルが類似したトラックを見つける
• カスタマイズ可能な特徴重み: 特定のオーディオ特徴に重みを付けることで、類似性計算を微調整
• 柔軟な検索範囲: 全体のカタログ、プレイリスト内、アーティストのディスコグラフィー、アルバム、または保存されたトラックを検索
• 自動アクション: 類似するトラックを見つけて、自動的にプレイリストを作成または既存のプレイリストに追加

🛠️ 利用可能なツール

基本ツール

1. spotify_search_tracks - 名前、アーティスト、またはクエリでトラックを検索
2. spotify_get_track - 特定のトラックの詳細情報を取得
3. spotify_get_recommendations - 調整可能なパラメータでトラックの推薦を取得
4. spotify_create_playlist - 新しいSpotifyプレイリストを作成
5. spotify_add_tracks_to_playlist - 既存のプレイリストにトラックを追加
6. spotify_get_user_playlists - ページネーションでユーザーのプレイリストを一覧表示
7. spotify_get_playlist_tracks - 特定のプレイリストからトラックを取得

高度な類似性ツール

8. spotify_get_audio_features - トラックの詳細なオーディオ特徴を取得
9. spotify_find_similar_tracks - 高度な類似性エンジン（詳細は以下を参照）

🔍 類似性エンジン

動作原理

類似性エンジンは、2つのアプローチを使用して類似するトラックを見つけます。

1. オーディオ特徴分析: エネルギー、テンポ、ダンス性などの音響特性を分析
2. ジャンルマッチング: アーティストのジャンルを比較して、スタイルベースの類似性を見つける

オーディオ特徴分析では、Spotifyのオーディオ分析APIを使用して、以下のような特徴を抽出します。

• 音響性 (0-1): トラックがアコースティック楽器を使用している確信度
• ダンス性 (0-1): ダンスに適している程度
• エネルギー (0-1): 強度と活動レベル
• インストゥルメンタル性 (0-1): ボーカルがない可能性
• バレンス (0-1): 音楽のポジティブさ（幸福度/元気さ）
• テンポ (BPM): トラックの速度
• 音量 (dB): 全体的な音量
• スピーチ性 (0-1): 話し言葉の存在
• ライブ性 (0-1): 観客の存在（ライブパフォーマンス）

類似性戦略

8種類の異なるアルゴリズムから選択できます。

1. euclidean (デフォルト) - ユークリッド距離を使用して、すべての特徴にわたる全体的な類似性
2. weighted - カスタム重み付き類似性 - 各特徴の重要度を指定
3. cosine - 角度類似性（高次元のマッチングに適しています）
4. manhattan - マンハッタン距離メトリック
5. energy_match - ワークアウト/パーティープレイリストのために、エネルギーとダンス性に焦点を当てる
6. mood_match - ムードベースのマッチングのために、バレンスと音響性に焦点を当てる
7. rhythm_match - リズムベースの類似性のために、テンポに焦点を当てる
8. genre_match - アーティストのジャンルに基づいてトラックをマッチング（完全一致と部分一致）

検索範囲

類似するトラックを検索する場所を制御できます。

• catalog - Spotifyの全体のカタログを検索（推薦APIを使用）
• playlist - 特定のプレイリスト内で類似するトラックを見つける
• artist - アーティストのディスコグラフィー内を検索
• album - 特定のアルバム内で類似するトラックを見つける
• saved_tracks - ユーザーの保存ライブラリ内を検索

アクション

類似するトラックに対して行うことを選択できます。

• return_tracks - 類似度スコア付きのトラックリストを返すだけ
• create_playlist - 類似するトラックで自動的に新しいプレイリストを作成
• add_to_playlist - 類似するトラックを既存のプレイリストに追加

📦 インストール

前提条件

1. Python 3.12以上 (miseで管理)
2. uv 依存関係管理用
3. Spotify開発者アカウント とAPI資格情報

セットアップ

1. リポジトリをクローンします。

git clone <repository-url>
cd spotify-playlist-mcp

2. 依存関係をインストールします。

uv sync

3. 環境変数を設定します。

cp .env.example .env
# .envを編集し、SPOTIFY_ACCESS_TOKENを追加

4. Spotifyアクセストークンを取得します（詳細な手順は .env.example を参照）。
   • Spotify開発者ダッシュボードにアクセスします。
   • アプリを作成します。
   • クライアントIDとクライアントシークレットを取得します。
   • 必要なスコープでアクセストークンを生成します。
     • playlist-modify-public
     • playlist-modify-private
     • playlist-read-private
     • user-read-private

💻 使用例

サーバーの起動

開発モード（MCPインスペクター付き）

uv run mcp dev server.py

直接実行

uv run python server.py

Claudeデスクトップ用にインストール

uv run mcp install server.py

具体的な使用例

プレイリスト内で類似するトラックを見つける

"Find songs similar to track [ID] within my workout playlist"

トラックに基づいてプレイリストを作成する

"Find tracks similar to [track name] using the energy_match strategy
and create a playlist called 'High Energy Workout'"

カスタム重み付き類似性

"Find tracks similar to this song, but prioritize energy and danceability
more than other features (weights: energy=5.0, danceability=5.0)"

アーティストのスタイルに基づいたムードベースのプレイリスト

"Create a calm acoustic playlist based on [artist name]'s style
using the mood_match strategy"

保存されたトラックを検索する

"Find all tracks in my saved library that sound similar to this song"

ジャンルベースのプレイリストフィルタリング

"Create a playlist with tracks from my Discover Weekly that have
the same genre as this track I'm listening to"

類似性エンジンの使用例

例1: プレイリスト内で類似するトラックを見つける

{
  "track_id": "3n3Ppam7vgaVa1iaRUc9Lp",
  "strategy": "euclidean",
  "scope": "playlist",
  "scope_id": "37i9dQZF1DXcBWIGoYBM5M",
  "limit": 10,
  "action": "return_tracks"
}

例2: 高エネルギーのワークアウトプレイリストを作成する

{
  "track_id": "4iV5W9uYEdYUVa79Axb7Rh",
  "strategy": "energy_match",
  "scope": "catalog",
  "limit": 30,
  "action": "create_playlist",
  "playlist_name": "High Energy Workout"
}

例3: カスタム重み付き類似性

{
  "track_id": "7qiZfU4dY1lWllzX7mPBI",
  "strategy": "weighted",
  "weights": {
    "energy": 5.0,
    "danceability": 5.0,
    "valence": 3.0,
    "acousticness": 0.5,
    "tempo": 2.0
  },
  "scope": "catalog",
  "limit": 20,
  "action": "create_playlist",
  "playlist_name": "Custom Mix"
}

例4: アーティストのスタイルで類似するトラックを見つける

{
  "artist_id": "0OdUWJ0sBjDrqHygGUXeCF",
  "strategy": "cosine",
  "scope": "saved_tracks",
  "limit": 15,
  "action": "add_to_playlist",
  "target_playlist_id": "5FqPqTauQoRPRxJBQC8C2N"
}

例5: ジャンルベースのプレイリストフィルタリング

特定のトラックのジャンルに一致するプレイリスト内のトラックを見つけます。

{
  "track_id": "3n3Ppam7vgaVa1iaRUc9Lp",
  "strategy": "genre_match",
  "scope": "playlist",
  "scope_id": "37i9dQZF1DXcBWIGoYBM5M",
  "limit": 20,
  "action": "create_playlist",
  "playlist_name": "Same Genre from Discover Weekly"
}

注意: genre_match 戦略は、特定の範囲（プレイリスト、アーティスト、アルバム、または保存されたトラック）が必要であり、カタログ範囲では機能しません。

🔧 技術詳細

モジュール化設計

類似性エンジンは、モジュール性を念頭に設計されています。

1. 特徴正規化 - オーディオ特徴を0-1の範囲に正規化
2. 類似性計算器 - プラガブルな距離/類似性関数
3. 範囲ハンドラー - 異なるソースから候補トラックを抽出
4. アクション実行器 - 異なる出力アクションを処理

カスタム戦略の追加

新しい類似性戦略を追加するには、以下の手順を実行します。

1. SimilarityStrategy 列挙型に戦略を追加します。
2. _calculate_similarity() で計算ロジックを実装します。
3. ツールの説明に戦略をドキュメント化します。

📄 APIリファレンス

spotify_find_similar_tracks

パラメータ:

• track_id (Optional[str]): ソーストラックID
• artist_id (Optional[str]): ソースアーティストID
• playlist_id (Optional[str]): ソースプレイリストID
• strategy (SimilarityStrategy): 使用するアルゴリズム
• weights (Optional[FeatureWeights]): カスタム特徴重み
• scope (SearchScope): 検索場所
• scope_id (Optional[str]): 範囲のID（プレイリスト/アーティスト/アルバム）
• limit (int): 結果の数 (1-100)
• min_similarity (Optional[float]): 最小類似度閾値
• action (SimilarityAction): 結果に対するアクション
• playlist_name (Optional[str]): 新しいプレイリストの名前
• target_playlist_id (Optional[str]): トラックを追加するターゲットプレイリストID
• response_format (ResponseFormat): 'markdown' または 'json'

返り値:

• 類似度スコア付きの類似トラックのリスト
• または、プレイリスト作成の確認
• または、プレイリストへの追加の確認

🐞 トラブルシューティング

オーディオ特徴が廃止されたエラー

オーディオ特徴が廃止されたというエラーが発生した場合は、以下を確認してください。

• Spotifyアプリで拡張モードアクセスを持っていることを確認してください。
• 注意: オーディオ特徴エンドポイントは、2024年11月に新しいアプリケーションでは廃止されました。拡張モードアクセスを持つ既存のアプリケーションは、引き続き使用できます。

認証エラー

• アクセストークンは1時間後に期限切れになります - 定期的に更新してください。
• すべての必要なスコープが付与されていることを確認してください。
• .env でトークンが正しく設定されていることを確認してください。

レート制限

• Spotify APIにはレート制限があります - サーバーは429エラーを適切に処理します。
• 大規模なプレイリストを検索する場合は、時間がかかることがあるので、耐心を持ってください。

🌟 ベストプラクティス

1. トークン管理: 本番環境では、トークンの更新ロジックを実装します。
2. 範囲選択: パフォーマンスを向上させるために、特定の範囲（プレイリスト/アーティスト/アルバム）を使用します。
3. 戦略選択:
   • 一般的な類似性には euclidean を使用します。
   • ワークアウト/パーティープレイリストには energy_match を使用します。
   • リラックス/勉強用のプレイリストには mood_match を使用します。
   • テンポベースのマッチング（ランニング、ダンス）には rhythm_match を使用します。
   • ジャンル類似性でプレイリストをフィルタリングするには genre_match を使用します。
   • どの特徴が最も重要かわかっている場合は、weighted を使用します。
4. ジャンルマッチの考慮事項:
   • 特定の範囲（プレイリスト、アーティスト、アルバム、または保存されたトラック）が必要です。
   • カタログ範囲では機能しません。
   • 既存のコレクションをジャンルでフィルタリングするのに最適です。
   • アーティストのジャンルを使用します（アーティストのジャンルデータがないトラックはスキップされます）。
5. バッチ操作: 複数のトラックを分析する場合は、バッチエンドポイントを使用します。
6. エラーハンドリング: 処理を続行する前に、常にレスポンスのエラーを確認します。

🤝 コントリビューション

コントリビューションは大歓迎です！改善の余地がある領域は以下の通りです。

• 追加の類似性戦略
• より洗練された特徴重み付けアルゴリズム
• BPM帯でのテンポ範囲マッチング
• キーとモードの互換性チェック
• オーディオ分析の統合（バー、ビート、セグメント）
• 高度なジャンル階層と分類法
• 複数アーティストのコラボレーション検出

🙏 謝辞

• FastMCPを使用して構築されており、MCP Python SDKにも登場しています。
• Spotify Web APIを使用しています。
• Model Context Protocol仕様に従っています。
• mcp-builder Claudeスキルを使用して、コード生成を改善しています。

🆘 サポート

問題、質問、または機能リクエストについては、GitHubでイシューを開いてください。