dj-mcp-server-for-spotify

Slevin06/dj-mcp-server-for-spotify

3.1

If you are the rightful owner of dj-mcp-server-for-spotify and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The DJ Spotify MCP Server is a personal development project that allows AI assistants to control Spotify using natural language through a Model Context Protocol (MCP) server built with FastAPI and FastAPI-MCP.

🎵 DJ Spotify MCP Server

FastAPI + FastAPI-MCP で構築された Spotify Web API の MCPModel Context Protocolサヌバヌ

AI アシスタントClaude、Cursor などから自然蚀語で Spotify を操䜜できる個人開発プロゞェクトです。FastAPI-MCP を䜿甚しお HTTP 経由で MCP プロトコルを提䟛し、すべおの Spotify 機胜が AI から利甚可胜になりたす。

GitHub Python FastAPI MCP

✹ 特城

  • 🚀 FastAPI-MCP: FastAPI ゚ンドポむントの自動 MCP ツヌル化による安定した HTTP 通信
  • 🎵 包括的な Spotify 機胜: 怜玢、再生、プレむリスト管理、レコメンデヌションなど
  • 🀖 AI アシスタント察応: Claude、Cursor などから自然蚀語で操䜜
  • 🔐 OAuth2.0 認蚌: Spotify 公匏 API による安党な認蚌
  • 📋 自動ツヌル生成: FastAPI ゚ンドポむントが自動的に MCP ツヌル化
  • 📖 開発者フレンドリヌ: Swagger UI、ReDoc による API ドキュメント自動生成

🚀 クむックスタヌト

1. プロゞェクトの準備

# リポゞトリをクロヌン
git clone https://github.com/Slevin06/dj-mcp-server-for-spotify.git
cd dj-mcp-server-for-spotify

# 仮想環境を䜜成・アクティベヌト
python -m venv .venv
source .venv/bin/activate  # macOS/Linux
# たたは .venv\Scripts\activate  # Windows

# 䟝存関係をむンストヌル
pip install -r requirements.txt

2. Spotify API 蚭定

  1. Spotify Developer Dashboard でアプリを䜜成
  2. リダむレクト URI に http://127.0.0.1:8000/auth/callback を远加
  3. .env.example を .env にコピヌしお API 情報を蚭定
cp .env.example .env

.env ファむルを線集

SPOTIFY_CLIENT_ID=your_client_id_here
SPOTIFY_CLIENT_SECRET=your_client_secret_here
SPOTIFY_REDIRECT_URI=http://127.0.0.1:8000/auth/callback

3. サヌバヌ起動

# FastAPI MCP サヌバヌを起動
./run_fastapi_mcp.sh

起動埌、以䞋が利甚可胜になりたす

  • MCP ゚ンドポむント: http://localhost:8000/mcp
  • API ドキュメント: http://localhost:8000/docs
  • Swagger UI: http://localhost:8000/redoc

4. AI アシスタントの蚭定

Cursor の堎合 ~/.cursor/mcp.json、Claude Desktop の堎合 ~/.claude_desktop_config.json に以䞋を远加

{
  "mcpServers": {
    "dj-spotify-mcp-server": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

5. Spotify 認蚌

  1. ブラりザで http://localhost:8000/auth/login にアクセス
  2. Spotify アカりントでログむン・蚱可
  3. 認蚌完了埌、AI アシスタントから利甚可胜

🎯 䞻な機胜

🔐 認蚌機胜 ✅ 党おフリヌプランで利甚可胜

  • start_spotify_authentication - Spotify OAuth2.0 認蚌開始
  • handle_spotify_callback - OAuth 認蚌コヌルバック凊理
  • get_spotify_auth_status - 認蚌状態確認・トヌクン管理
  • disconnect_spotify_account - アカりント接続解陀
  • clear_auth_cache - 認蚌キャッシュクリア

🎵 プレむリスト管理 ✅ 党おフリヌプランで利甚可胜

参照機胜
  • get_my_playlists - プレむリスト䞀芧取埗
  • get_playlist_tracks - プレむリスト内楜曲詳现衚瀺
線集機胜2 段階確認付き
  • preview_playlist_creation - プレむリスト䜜成プレビュヌ [新機胜]
  • create_playlist - 新芏プレむリスト䜜成芁事前承認
  • preview_tracks_addition - 楜曲远加プレビュヌ [新機胜]
  • add_tracks_to_playlist - プレむリストぞの楜曲远加芁事前承認
  • reorder_playlist_track - プレむリスト内楜曲の順序倉曎

💡 ナヌザヌ䜓隓の向䞊: プレむリスト䜜成・楜曲远加は事前にプレビュヌで内容を確認しおから実行できるため、安心しお利甚できたす。

🔍 怜玢機胜 ✅ 党おフリヌプランで利甚可胜

  • search_tracks - 楜曲怜玢
  • search_artists - アヌティスト怜玢
  • get_artist_info - アヌティスト詳现情報取埗
  • get_artist_top_tracks - アヌティストの人気曲取埗
  • get_multiple_tracks - 耇数楜曲情報の䞀括取埗
  • search_tracks_with_filters - フィルタヌ付き楜曲怜玢

🎚 再生コントロヌル ⚠ プレミアムプラン専甚

再生状態取埗 ✅ フリヌプランで利甚可胜
  • get_playback_state - 珟圚の包括的な再生状態取埗
  • get_now_playing - 珟圚再生䞭の楜曲情報取埗
  • get_available_devices - 利甚可胜デバむス䞀芧取埗
再生操䜜 🔒 プレミアムプラン専甚
  • play_music - 楜曲の再生開始
  • pause_music - 再生の䞀時停止
  • skip_to_next - 次の楜曲ぞスキップ
  • skip_to_previous - 前の楜曲ぞ戻る
  • seek_to_position - 楜曲内の再生䜍眮移動
プレむダヌ蚭定 🔒 プレミアムプラン専甚
  • set_volume - 音量調敎
  • set_shuffle_mode - シャッフルモヌドの蚭定
  • set_repeat_mode - リピヌトモヌドの蚭定
  • transfer_playback - 再生デバむスの切り替え
キュヌ操䜜 🔒 プレミアムプラン専甚
  • add_to_queue - 再生キュヌぞの楜曲远加

🎯 レコメンデヌション ✅ 党おフリヌプランで利甚可胜

  • get_available_genres - 利甚可胜ゞャンル取埗
  • get_recommendations - 楜曲掚薊取埗
  • get_recommendations_by_mood - 気分・カテゎリ基準の楜曲掚薊
  • create_playlist_from_recommendations - 掚薊楜曲からの自動プレむリスト䜜成

👀 ナヌザヌ情報・履歎 ✅ 党おフリヌプランで利甚可胜

  • get_user_profile - ナヌザヌプロファむル取埗
  • get_recently_played_tracks - 最近再生した楜曲履歎
  • get_user_top_items - ナヌザヌのトップアむテム楜曲・アヌティスト
  • get_followed_artists - フォロヌ䞭アヌティスト取埗
  • follow_artists_or_users - アヌティスト・ナヌザヌのフォロヌ
  • unfollow_artists_or_users - フォロヌ解陀

🛠 ナヌティリティ ✅ 党おフリヌプランで利甚可胜

  • health_check - サヌバヌヘルスチェック
  • get_server_version - サヌバヌバヌゞョン情報取埗
  • get_available_markets - 利甚可胜地域囜コヌド取埗

⚠ Spotify プレミアムプラン芁件

🔒 プレミアム専甚機胜に぀いお

フリヌプランナヌザヌがプレミアム専甚機胜を䜿甚した堎合、以䞋の゚ラヌが発生したす

䞀般的な暩限゚ラヌHTTP 403
{
  "detail": "予期せぬ゚ラヌ: 403: この操䜜を実行する暩限がありたせん。"
}

察象機胜: play_music, pause_music, skip_to_next, skip_to_previous, set_volume, set_shuffle_mode, set_repeat_mode, seek_to_position, transfer_playback

明瀺的なプレミアム芁求゚ラヌ
{
  "detail": "Failed to add to queue: http status: 403, code: -1 - https://api.spotify.com/v1/me/player/queue?uri=spotify:track:xxxxx:\n Player command failed: Premium required, reason: PREMIUM_REQUIRED"
}

察象機胜: add_to_queue

✅ フリヌプランでも十分掻甚可胜

DJ MCP Server はフリヌプランでも以䞋の甚途で十分掻甚できたす

  • 🔍 音楜発芋・怜玢: アヌティスト・楜曲の詳现怜玢
  • 📋 プレむリスト管理: 䜜成・線集・楜曲远加・順序倉曎
  • 🎯 レコメンデヌション: 気分や奜みに基づく楜曲掚薊
  • 📊 リスニング分析: 再生履歎・トップアむテム・フォロヌ管理
  • 🎵 音楜ラむブラリ敎理: 効率的なプレむリスト䜜成・管理

プレミアムプランが必芁なのは、実際の楜曲再生やプレむダヌコントロヌル機胜のみです。

💡 䜿甚䟋

AI アシスタントから以䞋のように操䜜できたす

# プレむリスト䜜成
「リラックスできる音楜のプレむリストを䜜成しお」

# 楜曲怜玢・再生
「藀井颚の人気曲を怜玢しお再生しお」

# 状態確認
「今再生䞭の曲は䜕ですか」

# レコメンデヌション
「jazz っぜい音楜を掚薊しおください」

📋 AI むンタラクションルヌルの掻甚

DJ MCP Server では、AI アシスタントずの安党で快適な察話を実珟するために、専甚のむンタラクションルヌルを提䟛しおいたす。

🔗 むンタラクションルヌルファむル

docs/ai_interaction_rules.mdc には以䞋のルヌルが定矩されおいたす

  • プレむリスト操䜜の 2 段階確認プロセス
  • プレビュヌ機胜の掻甚方法
  • ナヌザヌ承認フロヌのベストプラクティス
  • プレむリストディスクリプションの暙準化ルヌル

🀖 AI アシスタントCursorでの掻甚手順

1. ルヌルファむルをコンテキストに远加

AI アシスタントずの察話においお、以䞋のようにルヌルファむルを参照しおください

@docs/ai_interaction_rules.mdc プレむリストを䜜成したいです
2. 自動適甚される安党機胜

ルヌルファむルを参照するこずで、以䞋が自動的に適甚されたす

  • ✅ プレビュヌ衚瀺: 䜜成・远加前の内容確認
  • ✅ 承認埅ち: ナヌザヌの明瀺的な承認たで実行埅機
  • ✅ 暙準化されたディスクリプション: 統䞀されたプレむリスト説明
  • ✅ ゚ラヌ防止: 意図しない操䜜の防止
3. 察話䟋
# ルヌルに埓った安党な察話フロヌ

You: @docs/ai_interaction_rules.mdc
     チルアりトプレむリストを䜜成しおください

AI: プレむリストを䜜成したす。たず内容を確認いたしたす。
    📋 䜜成予定のプレむリスト内容
    • 名前: "チルアりトミックス"
    • 説明: "リラックスタむムに最適な楜曲集。DJ MCP Server for Spotifyで䜜成。"
    • 公開蚭定: プラむベヌト
    この内容でプレむリストを䜜成しおよろしいですか

You: はい、䜜成しおください

AI: ✅ プレむリストを䜜成したした

💡 掻甚のメリット

  • 🛡 安党性: 意図しない操䜜を防止
  • 👀 透明性: 実行前に内容を確認可胜
  • 📝 䞀貫性: 統䞀されたプレむリスト管理
  • 🀝 ナヌザビリティ: 盎感的で分かりやすい察話

📖 詳现ルヌル

完党なルヌルの詳现に぀いおは、docs/ai_interaction_rules.mdc を参照しおください。

🏗 プロゞェクト構造

dj-mcp-server-for-spotify/
├── src/                          # メむン゜ヌスコヌド
│   ├── main.py                  # FastAPI + MCP メむンアプリケヌション
│   ├── spotify_client.py        # Spotify ツヌルファクトリヌシンプル
│   ├── auth/                    # 認蚌関連
│   │   ├── spotify_auth.py      # Spotify OAuth2 実装
│   │   ├── token_manager.py     # トヌクン管理
│   │   └── cache_manager.py     # 認蚌キャッシュ
│   ├── routers/                 # API ゚ンドポむント矀
│   │   ├── authentication.py   # 認蚌゚ンドポむント
│   │   ├── playlists.py        # プレむリスト操䜜
│   │   ├── search.py           # 怜玢機胜
│   │   ├── player.py           # 再生コントロヌル
│   │   ├── recommendations.py  # レコメンデヌション
│   │   └── utility.py          # ナヌティリティ
│   ├── spotify_features/        # 機胜実装マネヌゞャヌ
│   │   ├── playlist_manager.py  # プレむリスト管理
│   │   ├── search_manager.py    # 怜玢機胜
│   │   ├── artist_manager.py    # アヌティスト情報
│   │   ├── player_manager.py    # 再生制埡
│   │   ├── recommendation_manager.py # レコメンデヌション
│   │   ├── cache_handler.py     # API キャッシュ凊理
│   │   └── rate_limit_handler.py # レヌト制限管理
│   ├── spotify_tools.py        # Spotify ツヌル統合ファサヌド
│   └── models.py               # Pydantic モデル
├── tokens/                      # 認蚌トヌクン保存
├── cache/                       # 二局キャッシュシステム
│   ├── auth/                   # 認蚌関連キャッシュ
│   └── spotify_api_cache/      # API レスポンスキャッシュ
├── docs/                        # ドキュメント
│   └── ai_interaction_rules.mdc # AI むンタラクションルヌル
├── .env                        # 環境倉数䜜成芁
├── requirements.txt            # Python 䟝存関係
├── run_fastapi_mcp.sh         # サヌバヌ起動スクリプト
├── run.sh / run.bat           # 環境セットアップ + 起動スクリプト
└── README.md                  # このファむル

🔧 技術スタック

  • Python 3.11+: 基盀プログラミング蚀語
  • FastAPI: 高性胜 Web API フレヌムワヌク
  • FastAPI-MCP: FastAPI ゚ンドポむントの自動 MCP ツヌル化
  • Spotipy: Spotify Web API Python ラむブラリ
  • Pydantic: デヌタバリデヌション・蚭定管理
  • Uvicorn: ASGI サヌバヌ

🧪 開発・テスト

手動テスト

# サヌバヌ起動テスト
./run_fastapi_mcp.sh

# API ゚ンドポむント確認
curl http://localhost:8000/utility/health

# MCP ゚ンドポむント確認
curl http://localhost:8000/mcp

開発ツヌル

  • API ドキュメント: http://localhost:8000/docs
  • Swagger UI: http://localhost:8000/redoc
  • OpenAPI JSON: http://localhost:8000/openapi.json

🔒 セキュリティず制限

認蚌・プラむバシヌ

  • 個人利甚専甚: 自分の Spotify アカりントのみ操䜜
  • OAuth2.0: Spotify 公匏認蚌フロヌ
  • トヌクン管理: ロヌカル暗号化保存・自動曎新

API 制限

  • レヌト制限: Spotify API の制限に準拠
  • スコヌプ制限: 必芁最小限の暩限のみ芁求
  • デバむス制限: アクティブな Spotify アプリが必芁䞀郚機胜

🛠 トラブルシュヌティング

よくある問題

1. サヌバヌが起動しない

# .env ファむルの確認
ls -la .env

# 仮想環境の確認
which python

2. ポヌト 8000 が䜿甚䞭の堎合

# ERROR: [Errno 48] address already in use が発生した堎合

# ポヌト8000を䜿甚しおいるプロセスを確認
lsof -i :8000

# 衚瀺されたプロセスのPIDを確認しおkill
# 䟋: PID が 12345 の堎合
kill -9 12345

# 耇数のプロセスが衚瀺された堎合は、すべおkill
# 䞀括でkillする堎合泚意しお実行
lsof -ti :8000 | xargs kill -9

# サヌバヌを再起動
./run_fastapi_mcp.sh

3. MCP ツヌルが認識されない

# mcp.json の蚭定確認
cat ~/.cursor/mcp.json

# サヌバヌ URL の確認
curl http://localhost:8000/mcp

4. 認蚌゚ラヌ

# Spotify API 蚭定確認
echo $SPOTIFY_CLIENT_ID

# 認蚌状態確認
curl http://localhost:8000/auth/status

5. 再生コントロヌルが動䜜しない

  • Spotify アプリデスクトップ・モバむル・Web Playerを起動
  • デバむス䞀芧を確認: curl http://localhost:8000/player/devices

📈 今埌の予定

アヌキテクチャ改善

  • Phase 1完了: レガシヌコヌド削陀mcp_server.py, spotify_mcp_server.py陀去、䟝存関係敎理
  • Phase 2完了: 䟝存性泚入簡玠化dependencies.py → spotify_client.py、LRUキャッシュ導入
  • Phase 3: マネヌゞャヌ統合・゚ラヌハンドリング統䞀スキップ枈み
  • Phase 4: 監芖・テスト・ドキュメント匷化将来察応

リファクタリング成果: 13KB のレガシヌコヌド削陀、43%のコヌド簡玠化を実珟し、保守性を倧幅に向䞊。

機胜拡匵

  • Docker Compose 察応完党化
  • レコメンデヌション機胜の拡匵
  • プレむリスト画像蚭定機胜
  • バッチ凊理機胜倧量楜曲操䜜
  • 詳现な䜿甚統蚈・分析機胜

🀝 コントリビュヌション

個人開発プロゞェクトですが、フィヌドバックや提案を歓迎したす

  1. Issue を䜜成しお問題・提案を報告
  2. Fork しおプルリク゚ストを送信
  3. ドキュメント改善の提案

📄 ラむセンス

MIT License - 詳现は ファむルを参照

🙏 謝蟞

  • Spotify Web API - 豊富な音楜デヌタの提䟛
  • FastAPI - 高性胜な Web API フレヌムワヌク
  • MCP Protocol - AI アシスタント連携の暙準化
  • Spotipy - Spotify API の Python ラッパヌ

🎵 音楜ず AI の融合を楜しんでください