Spotify MCP 서버

Spotify 웹 API 및 모델 컨텍스트 프로토콜(MCP)과 통합되어 Spotify 콘텐츠 검색, 재생 제어 및 관리 도구를 제공하는 Node.js 기반 서버입니다. 사용자는 stdio 전송을 통해 표준화된 MCP 인터페이스를 통해 Spotify 계정과 프로그래밍 방식으로 상호작용할 수 있습니다.

🧠 프로젝트 개요

이름: Spotify MCP 서버
설명: Spotify 웹 API를 MCP 표준과 연결하는 프로그래밍 가능한 인터페이스로, stdio를 통한 JSON 기반 도구를 사용하여 검색, 재생 제어 및 재생 목록 관리를 가능하게 합니다.
주요 특징:

• 🔍 Spotify에서 트랙 검색
• 🎵 현재 재생 상태 확인
• ▶️ URI로 특정 트랙 재생
• 📋 사용자 플레이리스트 검색
• ⏸ 재생 중인 항목을 일시 정지합니다.
• 🔐 Spotify를 사용한 OAuth 인증
• 📉 Spotify API 요청에 대한 속도 제한 처리

⚙️ 필수 조건

• Node.js (v16 이상 권장)
• 앱 자격 증명이 있는 Spotify 개발자 계정
• npm(노드 패키지 관리자)

📦 설치 단계

지엑스피1

참고: your_spotify_client_id 와 your_spotify_client_secret Spotify 개발자 앱 사용자 인증 정보로 바꾸세요. 리디렉션 URI는 Spotify 앱 설정에 설정된 URI와 일치해야 합니다.

이렇게 하면 Spotify 인증을 위한 브라우저가 열리고 stdio 전송을 사용하여 서버가 시작됩니다.

🔧 도구

1. search_tracks

• 설명: 쿼리 문자열을 기반으로 Spotify에서 트랙을 검색합니다.
• 입력 스키마:
  • query (문자열, 필수): 검색어(예: 아티스트 이름, 노래 제목).
• 출력: name , artist , album , release_date , popularity , id , uri 포함한 최대 5개의 트랙 객체로 구성된 JSON 배열입니다.
• 예:

2. get_playback_state .

• 설명: 사용자 Spotify 계정의 현재 재생 상태를 검색합니다.
• 입력 스키마: 없음
• 출력: 현재 트랙 정보, 재생 상태, 장치 세부 정보가 담긴 JSON 객체. 아무것도 재생되지 않으면 "활성 재생 없음"을 표시합니다.
• 예:

3. play_track

• 설명: Spotify URI를 사용하여 특정 트랙을 재생합니다.
• 입력 스키마:
  • uri (문자열, 필수): Spotify 트랙 URI(예: spotify:track:xxx ).
• 출력: status 와 uri 포함된 JSON 확인.
• 예:

4. get_user_playlists

• 설명: Spotify에서 사용자의 재생 목록을 가져옵니다.
• 입력 스키마:
  • limit (숫자, 선택 사항): 반환할 재생 목록의 최대 개수(기본값: 20).
• 출력: name , id , track_count , uri 및 public status를 포함한 재생 목록 객체의 JSON 배열입니다.
• 예:

5. pause_playback

• 설명: 사용자의 활성 Spotify 기기에서 현재 재생을 일시 중지합니다.
• 입력 스키마: 없음
• 출력: "재생 일시 정지" 상태를 나타내는 JSON 확인입니다.
• 예:

🌐 사용 사례

1. 음악 검색 봇:
   • search_tracks 와 play_track 사용하여 기분 기반 음악 챗봇을 구현합니다.
2. 재생목록 관리 도구:
   • get_user_playlists 와 search_tracks 사용하여 재생 목록을 미리 보고 구성하세요.
3. 재생 제어 자동화:
   • get_playback_state , play_track , pause_playback 사용하여 재생 작업을 자동화합니다.
4. Spotify 대시보드:
   • get_playback_state , get_user_playlists , pause_playback , play_track 사용하여 데스크톱 위젯을 빌드합니다.
5. Spotify API 배우기:
   • 모든 도구를 실험해 보면서 Spotify Web API가 어떻게 작동하는지 알아보세요.

🔐 인증 세부 정보

• 처음 실행 시, 서버는 Spotify OAuth 인증을 위해 브라우저를 엽니다.
• http://localhost:8888/callback 통해 코드를 수신합니다.
• 코드를 액세스 토큰과 새로 고침 토큰으로 교환합니다.
• 만료 후 5분 이내에 토큰을 자동으로 새로 고침합니다.

⏱ 속도 제한

• 재시도 전략을 사용하여 Spotify API 속도 제한을 처리합니다.
  • 각 요청 후 10초의 쿨다운이 발생합니다.
  • 429 요청이 너무 많습니다 오류가 발생하면 1분간 기다립니다.

📊 종속성

• dotenv : .env 에서 환경 변수를 로드합니다.
• spotify-web-api-node : Spotify API 클라이언트.
• @modelcontextprotocol/sdk : MCP 서버를 구현합니다.
• http , url : OAuth 리다이렉션 서버용 Node.js 내장 기능입니다.
• open : 인증을 위해 기본 브라우저를 엽니다.

📁 개발 정보

• 진입점: index.js
• 언어: JavaScript(ES 모듈이 포함된 Node.js)
• 실행 명령: node index.js
• 디버깅: 콘솔 로그에서 MCP 또는 인증 오류를 확인하세요.

⚠️ 제한 사항

• 재생 제어를 위해서는 Spotify Premium이 필요합니다.
• stdio 전송만 지원합니다(HTTP, WebSocket 등 불가).
• search_tracks 최대 5개의 결과를 반환합니다.
• 재생을 위해 단일 활성 장치가 사용된다고 가정합니다.

🚀 기여하기

다음 주소로 이슈를 공개하거나 풀 리퀘스트를 제출하세요.

• 새로운 도구 추가
• 기존 기능 강화
• 문서 개선

✍️ 라이센스

MIT 라이선스 - 개인적 또는 상업적 용도로 사용, 수정, 배포가 자유롭습니다.

❤️ 푸터

2025년 3월 17일 Rakshitha C Devadiga가 ❤️로 제작했습니다.