Skip to main content
Glama

spotify-mcp

Claude와 Spotify를 연결하는 Model Context Protocol (MCP) 서버입니다. Claude와의 자연스러운 대화를 통해 Spotify 재생 제어, 음악 검색, 재생 목록 관리 등을 수행할 수 있습니다.

포크 알림: 이 프로젝트는 varunneal/spotify-mcp에서 포크되었으며 Spotify Web API 2026년 2월 변경 사항에 맞춰 업데이트되었습니다. Claude Code를 사용하여 구축 및 유지 관리됩니다.

변경 사항 (v0.4.0)

아키텍처 재작성

  • spotipy 제거 -- httpx async를 직접 사용 (네이티브 async, asyncio.to_thread 래핑 없음)

  • 단일 모듈 -- server.py, spotify_api.py, utils.py를 하나의 파일로 통합

  • 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 개발자 앱 자격 증명

구성

1. Spotify 개발자 앱 생성

  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가 열려 있고 최소 하나의 장치에서 재생 중인지 확인하세요.

  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으로 축소

검색당 결과 수 감소

조정됨

재생 목록 엔드포인트 /tracks -> /items

엔드포인트 URL 변경

조정됨

응답 필드 tracks -> items

파싱 업데이트

조정됨

배치 GET 엔드포인트 제거

개별적으로 가져와야 함

조정됨

트랙에서 popularity 필드 제거

더 이상 사용 불가

처리됨

개발자 모드: 사용자 5명 제한, Premium 필수

액세스 제한

문서화됨

크레딧

라이선스

MIT 라이선스 -- 자세한 내용은 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