Skip to main content
Glama

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 API
  1. ClaudeがMCPプロトコルを介してツール呼び出しを送信

  2. サーバーがそれをhttpxを使用したSpotify Web APIリクエストに変換

  3. OAuthトークンは自動リフレッシュ。初回認証はspotify-mcp --authで実行

  4. 結果が簡潔なJSONに解析され、Claudeに返される

利用可能なツール

ツール

アクション

説明

spotify_playback

get, start, pause, skip, previous, volume

音楽再生と音量を制御

spotify_search

--

トラック、アルバム、アーティスト、プレイリストを検索

spotify_queue

get, add

再生キューの表示と管理

spotify_get_info

--

Spotify URIでアイテムの詳細情報を取得

spotify_playlist

get, get_tracks, add_tracks, remove_tracks, change_details, create, delete

プレイリストの完全な管理

spotify_liked_songs

get, get_with_genres, like, unlike, check

保存済み楽曲の管理とライブラリの確認

spotify_recently_played

--

最近再生したトラックをタイムスタンプ付きで取得

spotify_devices

list, transfer

デバイス一覧の取得と再生デバイスの切り替え

アーキテクチャ

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の作成

  1. developer.spotify.com/dashboardにアクセス

  2. 新しいアプリを作成

  3. リダイレクトURIをhttp://127.0.0.1:8080/callbackに設定

  4. 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.git

MCP設定(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 ID

SPOTIFY_CLIENT_SECRET

はい

--

SpotifyアプリのClient Secret

SPOTIFY_REDIRECT_URI

いいえ

http://127.0.0.1:8080/callback

OAuthリダイレクトURI

SPOTIFY_CACHE_PATH

いいえ

~/.spotify_mcp_cache.json

トークンキャッシュファイルのパス

トラブルシューティング

  1. 初回実行: MCPクライアントで使用する前に、spotify-mcp --authを実行してOAuthフローを完了させてください

  2. トークン期限切れ: トークンは自動的にリフレッシュされます。問題が続く場合は、再度--authを実行してください

  3. アクティブなデバイスがない: Spotifyが開いており、少なくとも1つのデバイスで再生中であることを確認してください

  4. uvの更新: バージョン>=0.54を推奨します

デバッグ

MCP Inspectorを起動します:

npx @modelcontextprotocol/inspector uv --directory /path/to/spotify-mcp run spotify-mcp

Spotify API 2026年2月の変更点まとめ

変更点

影響

ステータス

検索limitの最大値が50から10に減少

1検索あたりの結果数が減少

対応済み

プレイリストエンドポイント /tracks -> /items

エンドポイントURLが変更

対応済み

レスポンスフィールド tracks -> items

解析処理を更新

対応済み

バッチGETエンドポイントの削除

個別に取得する必要あり

対応済み

トラックのpopularityフィールド削除

利用不可

対応済み

開発モード: 5ユーザー制限、Premium必須

アクセス制限

ドキュメント化済み

クレジット

ライセンス

MIT License -- 詳細はLICENSEを参照してください。

Available Tools

6 tools
SpotifyGetInfoC

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

    B3.3/5.0

    Scored across 6 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      F
      maintenance
      An 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
    • A
      license
      A
      quality
      B
      maintenance
      MCP server for the Spotify Web API — gives Claude and other AI assistants tools to search music, control playback, manage playlists, library, and podcasts.
      47
      5
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An 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 npm
      9
      ISC
    • A
      license
      B
      quality
      D
      maintenance
      A Model Context Protocol server that enables searching and managing Spotify music, playlists, artists, albums, and audiobooks through natural language.
      24
      93 npm
      MIT