SpotifyMCP

Spotify Web API를 래핑하는 MCP 서버로, AI 어시스턴트(예: Claude)가 재생을 제어하고, 팟캐스트와 오디오북을 포함한 전체 카탈로그를 검색하며, 라이브러리와 플레이리스트를 관리하고, 사용자의 음악 취향을 파악할 수 있게 해줍니다.

왜 이 서버인가

대부분의 Spotify MCP 서버는 얇은 래퍼에 불과합니다. 이 서버는 기본값이 되도록 설계되었습니다:

• 완전한 API 표면 — 표준 개발자 토큰으로 호출 가능한 모든 비(非)deprecated Spotify Web API 엔드포인트가 도구로 제공됩니다(재생, 검색, 카탈로그, 오디오북, 개인화, 라이브러리, 플레이리스트, 팔로잉).

• deprecation에 대한 정직한 접근 — Spotify는 신규 앱에서 추천(recommendations), 관련 아티스트, 오디오 피처/분석, 장르 시드, 추천 플레이리스트를 제거했습니다. 이러한 기능을 여전히 노출하는 서버는 런타임에 실패하는 도구를 제공하지만, 이 서버는 그렇지 않습니다.

• 테스트 완료 — 클라이언트(토큰 갱신, rate limiting, 페이지네이션)와 모든 도구 핸들러에 대한 전체 단위 테스트 스위트, 그리고 엔드투엔드 MCP 프로토콜 스모크 테스트가 포함되어 있습니다. 많은 대안 서버는 테스트가 전혀 없습니다.

• 모든 것에 페이지네이션 — 라이브러리 및 플레이리스트 목록의 fetch_all은 한 페이지(50개)에서 조용히 잘리는 대신 모든 페이지를 순회합니다(최대 500개 항목).

• 팟캐스트가 일급 시민 — 에피소드는 모든 곳에서 작동합니다: 현재 재생 중, 대기열, 검색 후 재생. 여러 경쟁 서버는 팟캐스트를 전혀 볼 수 없습니다.

• 디바이스 인지 재생 — 디바이스 목록, 재생 전환, 모든 명령을 특정 디바이스에 지정하여 멀티룸 환경을 지원합니다.

• 견고한 인증 — 무음 갱신(silent refresh)이 포함된 PKCE 플로우, 영구 mode-600 토큰 캐시, 서버 및 컨테이너용 헤드리스 붙여넣기 플로우(SPOTIFY_HEADLESS=1).

Related MCP server: Spotify MCP Server

기능

재생 (15개 도구) — 현재 재생 중 / 현재 재생 폴링, 재생(URI로, 또는 play_from_search로 이름에서 바로 재생), 일시정지, 건너뛰기, 이전, 탐색, 볼륨, 셔플, 반복, 대기열 보기/추가, 디바이스 목록, 재생 전환.

검색 및 카탈로그 — 트랙/아티스트/앨범/플레이리스트/쇼/에피소드에 대한 통합 검색; 트랙, 아티스트, 아티스트 앨범, 앨범, 앨범 트랙, 쇼, 쇼 에피소드, 에피소드, 그리고 내 프로필(get_me)에 대한 심층 조회.

오디오북 — 타이틀, 챕터, 챕터 조회, 저장된 오디오북(Spotify에 의해 미국/영국/캐나다/아일랜드/뉴질랜드/호주로 시장 제한).

개인화 — 세 가지 시간 범위에 걸친 상위 트랙 및 아티스트, 최근 재생 목록.

라이브러리 — 저장된 트랙/앨범/쇼/에피소드(선택적 전체 페이지네이션 포함); /me/library URI를 통한 통합 저장/제거/확인.

플레이리스트 — 전체 CRUD 및 항목 관리(추가/제거/재정렬), 커버 아트 조회 및 맞춤 커버 업로드(업로드에는 ugc-image-upload 스코프 필요).

팔로잉 — 팔로우한 아티스트 목록 및 팔로우 상태 확인.

또한 제공: 7개의 MCP 리소스(프로필, 플레이어 상태, 대기열, 상위 트랙/아티스트, 최근 재생, 플레이리스트) 및 4개의 프롬프트 템플릿(DJ 세트, 무드 플레이리스트, 취향 요약, 발견 대안).

요구 사항 및 제한 사항

• 재생 제어에는 Spotify Premium이 필요합니다(재생, 일시정지, 건너뛰기, 탐색, 볼륨, 셔플, 반복, 대기열, 전환). 무료 계정은 인증하고 검색/카탈로그/라이브러리/플레이리스트 도구를 사용할 수 있지만, 모든 재생 명령은 Spotify의 Premium 필요 오류로 실패합니다.

• fetch_all 페이지네이션은 호출당 최대 500개 항목까지 순회합니다(무한 루프 방지). 그 이상은 limit/offset 페이징을 사용하세요.

• 오디오북 도구는 Spotify에 의해 미국, 영국, 캐나다, 아일랜드, 뉴질랜드, 호주로 시장 제한됩니다.

• Spotify의 개발자 모드는 확장 할당량이 부여될 때까지 앱당 최대 5명의 승인된 사용자를 허용합니다.

빠른 설정

1. Spotify 앱 만들기

각 사용자는 Client ID를 얻기 위해 자신의 Spotify 앱이 필요합니다. 이것은 Spotify가 어떤 앱이 API 요청을 하는지 식별하는 방법입니다.

1. Spotify Developer Dashboard로 이동하여 새 앱을 만듭니다.

2. 앱 설정에서 다음 Redirect URI를 정확히 추가합니다(일치하지 않으면 Spotify가 로그인을 거부합니다):

   http://127.0.0.1:8888/callback

3. 저장합니다. Client ID를 복사합니다.

2. 인증

아래 명령을 한 번 실행하여 Spotify 계정에 로그인합니다. your_client_id_here를 1단계의 Client ID로 바꿉니다. 브라우저 창이 열리고, 승인하면 토큰이 ~/.spotify-mcp/tokens.json에 저장됩니다. 서버가 자동으로 토큰을 갱신하므로 다시 수행할 필요가 없습니다.

macOS / Linux:

SPOTIFY_CLIENT_ID=your_client_id_here npx -y @novalux12/spotify-mcp@latest auth

헤드리스 / 원격 호스트(MCP 서버를 실행하는 머신에 브라우저가 없는 경우):

SPOTIFY_HEADLESS=1 SPOTIFY_CLIENT_ID=your_client_id_here npx -y @novalux12/spotify-mcp@latest auth

인증 URL이 출력됩니다. 아무 브라우저(예: 노트북)에서 플로우를 완료한 후, 리디렉션 URL을 프롬프트에 다시 붙여넣습니다. 홈랩, CI, 에이전트 런타임에 유용합니다.

헤드리스 인증(브라우저 없는 호스트)

브라우저가 없는 호스트(예: 클라우드 VM, Docker 컨테이너, 원격 서버)에서 이 MCP 서버를 실행하는 경우 SPOTIFY_HEADLESS=1 환경 변수를 설정하세요. 인증 플로우는 로컬 HTTP 콜백 서버를 건너뛰고, 브라우저에서 앱을 승인한 후 리디렉션 URL을 붙여넣도록 안내합니다.

단계

1. 환경에 SPOTIFY_HEADLESS=1을 설정합니다.

2. 서버를 실행합니다 — 앱을 승인할 URL이 출력됩니다.

3. 다른 머신의 브라우저에서 URL을 엽니다.

4. 승인 후 브라우저가 리디렉션 URI로 이동합니다.

5. 주소 표시줄에서 전체 URL을 복사합니다.

6. 서버 프롬프트에 다시 붙여넣습니다.

이유

기본 인증 플로우는 open 패키지를 통해 브라우저를 열고 127.0.0.1:8888에서 로컬 HTTP 콜백 서버를 실행합니다. 이는 MCP 서버가 헤드리스 호스트(홈랩, CI, 에이전트 런타임)에서 실행될 때 문제가 됩니다. open()할 브라우저가 없고, 사용자 머신에서 127.0.0.1:8888 콜백에 도달할 수 없기 때문입니다.

SPOTIFY_HEADLESS=1은 URL 붙여넣기 플로우로 전환합니다: 인증 URL이 stdout에 출력되고, 운영자가 아무 브라우저(노트북, 휴대폰)에서 플로우를 완료한 후 전체 리디렉션 URL을 다시 붙여넣습니다. 코드와 상태가 추출되어 서버 측에서 교환됩니다. 머신 간에 작동합니다.

Windows (Command Prompt):

set SPOTIFY_CLIENT_ID=your_client_id_here && npx -y @novalux12/spotify-mcp@latest auth

Windows (PowerShell):

$env:SPOTIFY_CLIENT_ID="your_client_id_here"; npx -y @novalux12/spotify-mcp@latest auth

3. Claude Desktop 구성

claude_desktop_config.json을 엽니다:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: Claude Desktop 열기 → 설정 → 개발자 → 구성 편집

mcpServers 블록을 추가합니다(your_client_id_here를 Client ID로 바꿉니다):

{
  "mcpServers": {
    "spotify": {
      "command": "npx",
      "args": ["-y", "@novalux12/spotify-mcp@latest"],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id_here"
      }
    }
  }
}

Claude Desktop을 완전히 종료하고 다시 시작합니다. 채팅 입력란의 망치 아이콘이 서버 연결을 확인해 줍니다.

대안: Claude Code

Claude Code를 사용하는 경우 JSON을 수동으로 편집하지 않고 서버를 추가할 수 있습니다:

claude mcp add spotify -- npx -y @novalux12/spotify-mcp@latest
# then set SPOTIFY_CLIENT_ID in your shell or MCP env:
export SPOTIFY_CLIENT_ID=your_client_id_here

또는 프로젝트 루트의 .mcp.json에 추가합니다 — 위와 동일한 command/args/env 형태입니다.

AI 에이전트용 명령

모든 코딩 에이전트(Claude Code, OpenClaw, Cursor, Aider 등)는 한 번의 붙여넣기로 설치, 빌드, 인증, 서버 등록을 수행할 수 있습니다. Client ID를 제공하고 실행하게 하세요:

git clone https://github.com/NovaLux12/spotify-mcp-server.git && cd spotify-mcp-server \
  && npm ci && npm run build \
  && SPOTIFY_CLIENT_ID=your_client_id_here npm run auth

그런 다음 호스트의 MCP 구성을 <repo>/dist/index.js로 지정하고 SPOTIFY_CLIENT_ID를 env에 포함시킵니다(형태는 아래 참조). 에이전트는 마지막에 get_me 도구를 한 번 호출해야 합니다. 이는 단일 왕복으로 인증, 스코프, 전송을 증명합니다.

OpenClaw

~/.openclaw/openclaw.json의 mcp.servers에 추가합니다:

"spotify": {
  "command": "node",
  "args": ["/path/to/spotify-mcp-server/dist/index.js"],
  "cwd": "/path/to/spotify-mcp-server",
  "env": { "SPOTIFY_CLIENT_ID": "your_client_id_here" }
}

그런 다음 OpenClaw 게이트웨이를 다시 시작하여 서버를 다시 생성합니다. 헤드리스 박스인가요? 브라우저가 있는 아무 머신에서 SPOTIFY_HEADLESS=1로 인증 단계를 실행하세요(위 참조) — 토큰은 어느 경우든 ~/.spotify-mcp/tokens.json에 저장됩니다.

문제 발생 시: doctor 스킬 설치

이 저장소에는 skills/spotify-mcp-doctor/SKILL.md가 포함되어 있습니다 — 이 README를 다시 읽는 대신 에이전트가 실행할 수 있는 절차적 진단 도구입니다. 실제 실패 모드를 순서대로 다룹니다: 연결 → 바이너리 → 앱 자격 증명 → 토큰 신선도 → 오류 분류(Premium vs 개발자 모드 허용 목록 vs 시장 제한 vs deprecation). 설치:

cp -r skills/spotify-mcp-doctor ~/.openclaw/workspace/skills/   # OpenClaw
# or drop it into .claude/skills/ for Claude Code projects

그런 다음 에이전트에게 이렇게 요청하세요: "Spotify 도구가 실패하고 있어 — spotify doctor 스킬을 실행해 줘."

사용법

연결되면 Claude에게 다음과 같이 요청할 수 있습니다:

• "내 상위 Spotify 트랙은 뭐야?"

• "공부용 차분한 lo-fi 노래 플레이리스트를 만들어 줘"

• "Blinding Lights라는 노래를 내 운동 플레이리스트에 추가해 줘"

• "최근에 가장 많이 들은 아티스트는 누구야?"

• "늦은 밤 드라이브 분위기의 플레이리스트를 만들어 줘"

문제 해결

• 첫 도구 호출 시 "인증되지 않음" — npx -y @novalux12/spotify-mcp@latest auth(또는 클론에서 npm run auth)를 실행하고 브라우저 플로우를 완료하세요. 토큰은 ~/.spotify-mcp/tokens.json에 저장되고 자동으로 갱신됩니다.

• Redirect URI 불일치 — Spotify 앱의 redirect URI는 정확히 http://127.0.0.1:8888/callback이어야 합니다(끝에 슬래시 없음). 앱 설정을 저장하고 다시 시도하세요.

• 포트 8888 사용 중 — 다른 프로세스가 콜백 포트를 점유하고 있습니다. 중지하거나 SPOTIFY_REDIRECT_URI=http://127.0.0.1:8888/callback로 다른 포트를 사용하고 Dashboard 설정도 일치시키세요.

• 헤드리스 / Docker — auth 전에 SPOTIFY_HEADLESS=1을 설정하고, 프롬프트가 표시되면 리디렉션 URL을 붙여넣으세요(위 참조).

면책 조항

이것은 개인 프로젝트로, Spotify와 제휴하거나 보증하지 않습니다. 어떠한 종류의 보증이나 보장 없이 있는 그대로 제공됩니다. 책임감 있게 Spotify Developer Terms of Service에 따라 사용하세요. 저자는 이 소프트웨어 사용으로 인한 오용이나 결과에 대해 책임을 지지 않습니다.

개발

git clone https://github.com/NovaLux12/spotify-mcp-server.git
cd spotify-mcp-server
npm install
npm run build

.env.example을 .env로 복사하고 Client ID를 입력한 후:

npm run auth   # authenticate with Spotify
npm run dev    # run from source (no build needed)

Node 22.9+ 필요(--env-file-if-exists 지원). .env 파일은 필요 없습니다 — 환경 변수는 호스트 구성 또는 명령줄에서 제공됩니다.

테스트

npm test   # node:test runner — unit tests for the client and every tool module, plus an MCP protocol smoke test

감사의 말

• calebWei/SpotifyMCP — 이 프로젝트가 성장한 원래 인증 플로우 및 재생 스캐폴딩.

• varunneal/spotify-mcp — 도구 범위와 사용성의 품질 기준으로 사용된 참조 구현.

라이선스

MIT © Carme99 및 NovaLux12 기여자.