Vulpes Spotify MCP Server

Vuples Spotify MCP 서버

Claude와 같은 AI 비서가 Spotify와 상호 작용하여 트랙을 검색하고 재생할 수 있도록 하는 MCP(Model Context Protocol) 서버입니다.

특징

• 아티스트, 제목 또는 기타 쿼리로 트랙을 검색하세요.
• 활성 Spotify 기기에서 직접 트랙을 재생하세요
• 현재 재생 중인 트랙에 대한 정보를 얻으세요
• 사용 가능한 Spotify 재생 장치 찾기
• 결합된 검색 및 재생 기능
• 사용자의 Spotify 재생목록 나열
• 재생 목록 내 트랙 보기
• 재생 목록 재생(셔플 모드 옵션 포함)
• 이름으로 재생목록을 찾아 재생합니다

요구 사항

• Node.js(v16+)
• Spotify 개발자 계정
• Spotify Premium 계정(재생 기능용)
• MCP 호환 클라이언트(예: Claude Desktop)

설치

1. 이 저장소를 복제하세요:지엑스피1
2. 종속성 설치:
   npm install
3. Spotify API 자격 증명으로 .env 파일을 만듭니다.
   SPOTIFY_CLIENT_ID=your_client_id SPOTIFY_CLIENT_SECRET=your_client_secret SPOTIFY_REDIRECT_URI=http://localhost:8888 # Optional: For playback control SPOTIFY_REFRESH_TOKEN=your_refresh_token
   Spotify 개발자 대시보드 에서 클라이언트 ID와 비밀번호를 얻을 수 있습니다.
4. 새로 고침 토큰을 생성합니다(재생 제어에 필요):새로 고침 토큰을 얻는 방법은 두 가지가 있습니다.옵션 1: 내장 스크립트 사용
   npm run get-token
   이렇게 하면 로컬 서버가 시작되고 터미널에 지침이 제공됩니다.옵션 2: 간단한 스크립트를 사용하세요(옵션 1이 작동하지 않는 경우)
   node src/simple-auth.js
   브라우저에서 열 수 있는 URL이 제공됩니다. 권한을 부여하면 해당 URL로 리디렉션됩니다. 해당 URL을 터미널에 다시 복사하면 새로 고침 토큰을 얻는 curl 명령어가 표시됩니다.필수 범위(스크립트에 이미 포함됨):
   • user-read-playback-state
   • user-modify-playback-state
   • user-read-currently-playing
   • playlist-read-private
   • playlist-read-collaborative
5. .env 파일에 새로 고침 토큰을 추가합니다.
   SPOTIFY_REFRESH_TOKEN=your_refresh_token
6. 프로젝트를 빌드하세요:
   npm run build

Claude Desktop과 함께 사용

1. 먼저 Spotify가 열려 있고 기기에서 재생 중인지 확인하세요.
2. Claude Desktop 구성에 이 서버를 추가하세요:claude_desktop_config.json 파일을 편집합니다(일반적으로 macOS에서는 ~/Library/Application Support/Claude/ 에 있고 Windows에서는 %APPDATA%\\Claude\\ 에 있음):
   { "mcpServers": { "spotify": { "command": "node", "args": ["/absolute/path/to/vulpes-spotify-mcp/dist/index.js"], "env": { "SPOTIFY_CLIENT_ID": "your_client_id", "SPOTIFY_CLIENT_SECRET": "your_client_secret", "SPOTIFY_REDIRECT_URI": "http://localhost:8888", "SPOTIFY_REFRESH_TOKEN": "your_refresh_token" } } } }
   /absolute/path/to/vulpes-spotify-mcp 프로젝트의 실제 경로로 바꿔야 합니다.
3. Claude Desktop을 다시 시작하세요
4. 이제 Claude Desktop의 망치 아이콘을 클릭하면 사용 가능한 Spotify 도구가 표시됩니다.

사용 가능한 도구

• spotify-search : 쿼리로 트랙 검색
• spotify-play : ID 또는 URI로 특정 트랙 재생
• spotify-currently-playing : 현재 재생 중인 트랙에 대한 정보를 가져옵니다.
• spotify-devices : 사용 가능한 Spotify 재생 장치 목록
• spotify-search-and-play : 트랙을 검색하고 상위 결과를 자동으로 재생합니다.
• spotify-playlists : 사용자의 Spotify 재생 목록 목록을 가져옵니다.
• spotify-playlist-tracks : 특정 재생 목록에서 트랙 가져오기
• spotify-play-playlist : 특정 재생목록 재생(셔플 기능 옵션 포함)
• spotify-find-playlist : 이름으로 플레이리스트를 찾아 재생합니다(AI 사용에 권장)

문제 해결

• "활성 장치를 찾을 수 없습니다" : Spotify가 열려 있고 적어도 하나의 장치에서 재생 중인지 확인하세요.
• "권한 없음" : 새로 고침 토큰에 필요한 범위가 없을 수 있습니다.
• "프리미엄 아님" : 재생 제어에는 Spotify 프리미엄 계정이 필요합니다.
• "새로 고침 토큰 문제" : 토큰이 만료된 경우 설치 섹션의 단계에 따라 새 토큰을 생성하세요.

중요 참고 사항

1. 재생 컨트롤을 사용하기 전에 항상 최소한 한 대의 기기에서 Spotify가 열려 있는지 확인하세요.
2. .env 파일과 Claude Desktop 구성의 새로 고침 토큰은 일치해야 합니다.
3. 구성을 변경한 후 Claude Desktop을 다시 시작하세요.

특허

MIT