spotify-mcp
spotify-mcp
Claude와 Spotify를 연결하는 Model Context Protocol (MCP) 서버입니다. Claude와의 자연스러운 대화를 통해 Spotify 재생 제어, 음악 검색, 재생 목록 관리 등을 수행할 수 있습니다.
포크 알림: 이 프로젝트는 varunneal/spotify-mcp에서 포크되었으며 Spotify Web API 2026년 2월 변경 사항에 맞춰 업데이트되었습니다. Claude Code를 사용하여 구축 및 유지 관리됩니다.
변경 사항 (v0.4.0)
아키텍처 재작성
spotipy제거 --httpxasync를 직접 사용 (네이티브 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 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 개발자 앱 자격 증명
구성
1. Spotify 개발자 앱 생성
developer.spotify.com/dashboard로 이동합니다.
새 앱을 생성합니다.
리디렉션 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가 열려 있고 최소 하나의 장치에서 재생 중인지 확인하세요.
uv업데이트 확인 -->=0.54버전 권장
디버깅
MCP Inspector 실행:
npx @modelcontextprotocol/inspector uv --directory /path/to/spotify-mcp run spotify-mcpSpotify API 2026년 2월 변경 사항 요약
변경 사항 | 영향 | 상태 |
검색 | 검색당 결과 수 감소 | 조정됨 |
재생 목록 엔드포인트 | 엔드포인트 URL 변경 | 조정됨 |
응답 필드 | 파싱 업데이트 | 조정됨 |
배치 GET 엔드포인트 제거 | 개별적으로 가져와야 함 | 조정됨 |
트랙에서 | 더 이상 사용 불가 | 처리됨 |
개발자 모드: 사용자 5명 제한, Premium 필수 | 액세스 제한 | 문서화됨 |
크레딧
원본 프로젝트: Varun Srivastava의 varunneal/spotify-mcp (MIT 라이선스)
원본 기여자: @jamiew, @davidpadbury, @manncodes, @hyuma7, @aanurraj, @JJGO 외 다수
유지 관리 도구: Claude Code (Anthropic)
라이선스
MIT 라이선스 -- 자세한 내용은 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