spotify-mcp
spotify-mcp
ClaudeとSpotifyを接続するModel Context Protocol (MCP)サーバーです。Spotifyの再生制御、音楽検索、プレイリスト管理などを、Claudeとの自然な会話を通じて行えます。
フォークに関する注意: 本プロジェクトはvarunneal/spotify-mcpからフォークされ、2026年2月のSpotify Web APIの変更に対応したものです。Claude Codeを使用して構築・保守されています。
変更点 (v0.4.0)
アーキテクチャの書き換え
spotipyを廃止 --httpxの非同期処理を直接使用(ネイティブ非同期、asyncio.to_threadによるラップなし)シングルモジュール化 --
server.py、spotify_api.py、utils.pyを1つのファイルに統合FastMCP -- 手動のToolModelやmatch/caseルーティングではなく、クリーンな
@mcp.tool()デコレーターを採用依存関係を2つに削減 --
mcp+httpxのみ(以前はmcp+spotipy+python-dotenv)明示的なOAuth -- 初回セットアップ用に
spotify-mcp --authを追加、以降は自動リフレッシュ
機能 (v0.3.0から継承)
再生の開始、一時停止、スキップ
トラック、アルバム、アーティスト、プレイリストの検索
Spotifyアイテムの詳細情報の取得
再生キューの管理
プレイリストの完全なCRUD(トラックの作成、読み取り、更新、削除)
いいね/保存済み楽曲の取得(オプションでジャンル情報を付加)
Spotify 2026年2月のAPI変更に対応
Related MCP server: Spotify MCP Server
仕組み
Claude <--MCP (stdio)--> spotify-mcp <--httpx async--> Spotify Web APIClaudeがMCPプロトコルを介してツール呼び出しを送信
サーバーがそれを
httpxを使用したSpotify Web APIリクエストに変換OAuthトークンは自動リフレッシュ。初回認証は
spotify-mcp --authで実行結果が簡潔なJSONに解析され、Claudeに返される
利用可能なツール
ツール | アクション | 説明 |
|
| 音楽再生と音量を制御 |
| -- | トラック、アルバム、アーティスト、プレイリストを検索 |
|
| 再生キューの表示と管理 |
| -- | Spotify URIでアイテムの詳細情報を取得 |
|
| プレイリストの完全な管理 |
|
| 保存済み楽曲の管理とライブラリの確認 |
| -- | 最近再生したトラックをタイムスタンプ付きで取得 |
|
| デバイス一覧の取得と再生デバイスの切り替え |
アーキテクチャ
src/spotify_mcp/
__init__.py # Entry point (stdio / --auth)
server.py # FastMCP server, API client, parsers — all in one前提条件
Python 3.12+
Spotify Premiumアカウント(2026年2月以降、開発モードのAPIアクセスに必須)
Spotify Developer Appの認証情報
設定
1. Spotify Developer Appの作成
新しいアプリを作成
リダイレクトURIを
http://127.0.0.1:8080/callbackに設定Client IDとClient Secretを控える
重要 (2026年2月): 開発モードのアプリは承認済みユーザーが5名までに制限されており、アプリ所有者がSpotify Premiumに加入している必要があります。
2. 初回認証
認証フローを一度実行してOAuthトークンを取得します:
SPOTIFY_CLIENT_ID=your_id SPOTIFY_CLIENT_SECRET=your_secret uv run spotify-mcp --authこれによりブラウザが開きSpotifyのログイン画面が表示されます。完了後、トークンが~/.spotify_mcp_cache.jsonに保存されます。
3. MCPクライアントへの追加
ローカルで実行(推奨)
git clone https://github.com/verIdyia/spotify-mcp.gitMCP設定(Claude Desktop、Cursorなど)に追加します:
{
"mcpServers": {
"spotify": {
"command": "uv",
"args": [
"--directory",
"/path/to/spotify-mcp",
"run",
"spotify-mcp"
],
"env": {
"SPOTIFY_CLIENT_ID": "your_client_id",
"SPOTIFY_CLIENT_SECRET": "your_client_secret",
"SPOTIFY_REDIRECT_URI": "http://127.0.0.1:8080/callback"
}
}
}
}uvxで実行
{
"mcpServers": {
"spotify": {
"command": "uvx",
"args": [
"--python", "3.12",
"--from", "git+https://github.com/verIdyia/spotify-mcp",
"spotify-mcp"
],
"env": {
"SPOTIFY_CLIENT_ID": "your_client_id",
"SPOTIFY_CLIENT_SECRET": "your_client_secret",
"SPOTIFY_REDIRECT_URI": "http://127.0.0.1:8080/callback"
}
}
}
}環境変数
変数 | 必須 | デフォルト | 説明 |
| はい | -- | SpotifyアプリのClient ID |
| はい | -- | SpotifyアプリのClient Secret |
| いいえ |
| OAuthリダイレクトURI |
| いいえ |
| トークンキャッシュファイルのパス |
トラブルシューティング
初回実行: MCPクライアントで使用する前に、
spotify-mcp --authを実行してOAuthフローを完了させてくださいトークン期限切れ: トークンは自動的にリフレッシュされます。問題が続く場合は、再度
--authを実行してくださいアクティブなデバイスがない: Spotifyが開いており、少なくとも1つのデバイスで再生中であることを確認してください
uvの更新: バージョン>=0.54を推奨します
デバッグ
MCP Inspectorを起動します:
npx @modelcontextprotocol/inspector uv --directory /path/to/spotify-mcp run spotify-mcpSpotify API 2026年2月の変更点まとめ
変更点 | 影響 | ステータス |
検索 | 1検索あたりの結果数が減少 | 対応済み |
プレイリストエンドポイント | エンドポイントURLが変更 | 対応済み |
レスポンスフィールド | 解析処理を更新 | 対応済み |
バッチGETエンドポイントの削除 | 個別に取得する必要あり | 対応済み |
トラックの | 利用不可 | 対応済み |
開発モード: 5ユーザー制限、Premium必須 | アクセス制限 | ドキュメント化済み |
クレジット
オリジナルプロジェクト: varunneal/spotify-mcp by Varun Srivastava (MIT License)
オリジナル貢献者: @jamiew, @davidpadbury, @manncodes, @hyuma7, @aanurraj, @JJGO 他
保守に使用: Claude Code (Anthropic)
ライセンス
MIT License -- 詳細はLICENSEを参照してください。
Available Tools
6 toolsSpotifyGetInfoC
Get detailed information about a Spotify item...
Inputs: item_uri (required).
SpotifyLikedSongsC
Get user's liked (saved) songs from Spotify library.
Inputs: action (required), limit.
SpotifyPlaybackC
Manages the current playback...
Inputs: action (required), spotify_uri, num_skips.
SpotifyPlaylistC
Manage Spotify playlists.
Inputs: action (required), playlist_id, track_ids, name, +2 more.
SpotifyQueueC
Manage the playback queue - get the queue or add tracks.
Inputs: action (required), track_id.
SpotifySearchC
Search for tracks, albums, artists, or playlists on Spotify.
Inputs: query (required), qtype, limit.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool has a clearly distinct purpose targeting different Spotify resources: GetInfo for item details, LikedSongs for saved songs, Playback for current playback control, Playlist for playlist management, Queue for queue operations, and Search for finding content. There is no overlap or ambiguity between these functions.
All tools follow a consistent 'Spotify' prefix with descriptive noun-based naming (e.g., SpotifyGetInfo, SpotifyPlaylist). The pattern is uniform across all six tools, making them easily identifiable and predictable.
With 6 tools, this server is well-scoped for Spotify integration, covering key areas like playback, playlists, search, and user library. Each tool serves a specific, necessary function without bloat or redundancy.
The toolset covers core Spotify functionalities including search, playback control, playlist management, and user data access. Minor gaps might include operations like following artists or managing user profile settings, but the provided tools support most common workflows effectively.
Maintenance
Related MCP Connectors
MCP server for Producer/Riffusion AI music generation
MCP server for progressive tool usage at any scale (see https://klavis.ai)
Official Todoist MCP server. Manage tasks and projects. Hosted, no API key needed.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Related MCP Servers
- AlicenseNot gradedqualityFmaintenanceAn MCP server that enables users to control Spotify playback, search for music, and manage playlists through MCP-compatible clients. It supports features like track recommendations and playback management using secure OAuth authentication.MIT
- AlicenseAqualityBmaintenanceMCP server for the Spotify Web API — gives Claude and other AI assistants tools to search music, control playback, manage playlists, library, and podcasts.475MIT
- AlicenseNot gradedqualityDmaintenanceAn unofficial MCP server that provides access to Spotify's Web API through the Model Context Protocol, enabling AI assistants to search music, manage playlists, and control playback.29 npm9ISC
- AlicenseBqualityDmaintenanceA Model Context Protocol server that enables searching and managing Spotify music, playlists, artists, albums, and audiobooks through natural language.2493 npmMIT