MCP 클로드 스포티파이

특징

• Spotify 인증
• 트랙, 앨범, 아티스트 및 재생 목록을 검색하세요
• 재생 제어(재생, 일시정지, 다음, 이전)
• 재생목록 만들기 및 관리
• 개인화된 추천을 받으세요
• 다양한 기간 동안 사용자가 가장 많이 재생한 트랙에 액세스하세요.

데모

요구 사항

• Node.js 16 이상
• Spotify 계정
• 클로드 데스크탑
• Spotify API 자격 증명(클라이언트 ID 및 클라이언트 비밀번호)

설치

Smithery를 통해 설치

Smithery 를 통해 Claude Desktop용 MCP Claude Spotify를 자동으로 설치하려면:

지엑스피1

수동 설치

1. 이 저장소를 복제하거나 다운로드하세요:

2. 종속성 설치:

3. 프로젝트를 빌드합니다(소스 코드를 수정하려는 경우):

저장소에는 이미 build 디렉토리에 미리 빌드된 파일이 포함되어 있으므로 소스 코드를 수정할 계획이 없다면 3단계를 건너뛸 수 있습니다.

Spotify 자격 증명 설정

이 MCP를 사용하려면 Spotify API 자격 증명을 얻어야 합니다.

1. Spotify 개발자 대시보드 로 이동
2. Spotify 계정으로 로그인하세요
3. "앱 만들기"를 클릭하세요
4. 앱 정보를 입력하세요:
   • 앱 이름: "MCP Claude Spotify"(또는 원하는 이름)
   • 앱 설명: "Claude Desktop용 Spotify 통합"
   • 웹사이트: 이 부분은 비워두거나 원하는 URL을 입력할 수 있습니다.
   • 리디렉션 URI: 중요 - http://127.0.0.1:8888/callback 추가하세요
5. 이용 약관에 동의하고 "만들기"를 클릭하세요.
6. 앱 대시보드에서 "클라이언트 ID"를 볼 수 있습니다.
7. "클라이언트 비밀번호 표시"를 클릭하여 "클라이언트 비밀번호"를 표시합니다.

구성에 필요하므로 이 자격 증명을 저장해 두세요.

MCP 서버 실행

MCP 서버를 실행하는 방법은 두 가지가 있습니다.

옵션 1: 수동 실행(최초 설정 및 문제 해결 시 권장)

1. 터미널이나 명령 프롬프트를 엽니다
2. 프로젝트 디렉토리로 이동합니다
3. 서버를 직접 실행합니다.

Claude Desktop을 사용하는 동안 이 터미널 창을 열어 두세요. 터미널을 닫을 때까지 서버가 실행됩니다.

옵션 2: Claude Desktop으로 자동 시작(일반 사용 시 권장)

Claude Desktop은 필요 시 MCP 서버를 자동으로 시작할 수 있습니다. 설정 방법은 다음과 같습니다.

구성

Claude Desktop 구성 파일은 다음 위치에 있습니다.

• macOS : ~/Library/Application Support/Claude/claude_desktop_config.json
• 윈도우 : %APPDATA%\Claude\claude_desktop_config.json

이 파일을 편집하여 Spotify MCP 구성을 추가하세요. 파일이 없으면 새로 만드세요.

중요 : 교체:

• MCP를 설치한 전체 절대 경로를 포함하는 ABSOLUTE_PATH_TO_DIRECTORY
  • macOS/Linux 예: /Users/username/mcp-claude-spotify
  • Windows 예: C:\\Users\\username\\mcp-claude-spotify
• Spotify에서 얻은 클라이언트 ID를 your_client_id_here 에 입력하세요.
• Spotify에서 얻은 클라이언트 비밀번호를 your_client_secret_here 에 입력합니다.

이미 다른 MCP를 구성한 경우 "mcpServers" 개체 내부에 "spotify" 섹션을 추가하기만 하면 됩니다.

자동 시작 스크립트 설정(선택 사항)

더욱 안정적인 환경을 위해 자동 시작 스크립트를 설정할 수 있습니다.

1. 프로젝트 디렉토리에 다음 내용으로 start-spotify-mcp.bat 이라는 이름의 파일을 만듭니다.

2. 이 BAT 파일에 대한 바로가기를 만듭니다
3. Win+R 누르고 shell:startup 입력한 후 Enter를 누릅니다.
4. Windows에서 시작하려면 이 폴더로 바로 가기를 이동하세요.
5. ~/Library/LaunchAgents/ 에 다음 내용으로 com.spotify.mcp.plist 라는 이름의 파일을 만듭니다.

2. 경로와 자격 증명을 실제 값으로 바꾸세요.
3. 다음을 사용하여 에이전트를 로드합니다. launchctl load ~/Library/LaunchAgents/com.spotify.mcp.plist
4. ~/.config/systemd/user/ 에 spotify-mcp.service 라는 이름의 파일을 만듭니다(디렉토리가 없으면 만듭니다).

2. 경로와 자격 증명을 실제 값으로 바꾸세요.
3. 서비스를 활성화하고 시작합니다.

4. 다음을 사용하여 상태를 확인하세요.

용법

1. 구성을 수정한 후 Claude Desktop을 다시 시작하세요.
2. Claude에서 auth-spotify 명령을 사용하여 인증 프로세스를 시작합니다.
3. 애플리케이션을 승인하기 위한 브라우저 창이 열립니다.
4. Spotify 계정으로 로그인하고 애플리케이션을 승인하세요.
5. 중요 : 인증에 성공한 후 Claude Desktop을 다시 시작하여 MCP의 도구 레지스트리와 WebSocket 세션 토큰 캐시를 올바르게 초기화합니다.
6. 재시작 후 모든 Spotify MCP 도구가 제대로 등록되어 사용할 수 있습니다.

MCP 서버는 Claude Desktop이 관리하는 자식 프로세스로 실행됩니다. Claude가 실행 중이면 claude_desktop_config.json 파일의 구성에 따라 Node.js 서버 프로세스가 자동으로 시작되고 관리됩니다.

사용 가능한 도구

인증-스포티파이

Spotify 인증 프로세스를 시작합니다.

검색-스포티파이

트랙, 앨범, 아티스트 또는 재생 목록을 검색합니다.

매개변수:

• query : 검색 텍스트
• type : 검색 유형(트랙, 앨범, 아티스트, 재생 목록)
• limit : 결과 수(1-50)

플레이 트랙

특정 트랙을 재생합니다.

매개변수:

• trackId : Spotify 트랙 ID
• deviceId : (선택 사항) 재생할 Spotify 기기 ID

현재 재생 가져오기

현재 재생에 대한 정보를 가져옵니다.

일시 정지-재생

재생을 일시 정지합니다.

다음 트랙

다음 트랙으로 넘어갑니다.

이전 트랙

이전 트랙으로 돌아갑니다.

사용자 재생목록 가져오기

사용자의 재생목록을 가져옵니다.

재생목록 만들기

새로운 재생목록을 만듭니다.

매개변수:

• name : 플레이리스트 이름
• description : (선택 사항) 설명
• public : (선택사항) 공개인지 비공개인지

재생목록에 트랙 추가

재생목록에 트랙을 추가합니다.

매개변수:

• playlistId : 재생목록 ID
• trackIds : 트랙 ID 배열

추천 받기

씨앗을 기반으로 추천을 받습니다.

매개변수:

• seedTracks : (선택 사항) 트랙 ID 배열
• seedArtists : (선택 사항) 아티스트 ID 배열
• seedGenres : (선택 사항) 장르 배열
• limit : (선택사항) 추천 개수 (1~100)

최고의 트랙을 얻으세요

지정된 기간 동안 사용자가 가장 많이 재생한 트랙을 가져옵니다.

매개변수:

• limit : (선택 사항) 반환할 트랙 수(1-50, 기본값: 20)
• offset : (선택 사항) 반환할 첫 번째 트랙의 인덱스(기본값: 0)
• time_range : (선택 사항) 친화도 계산을 위한 시간 범위:
  • short_term : 대략 지난 4주
  • medium_term : 대략 지난 6개월(기본값)
  • long_term : 몇 년간의 데이터

문제 해결

"서버 연결 끊김" 오류

Claude Desktop에서 "MCP Spotify: 서버 연결 끊김" 오류가 표시되는 경우:

1. 서버가 실행 중인지 확인하세요 .
   • 터미널을 열고 프로젝트 디렉토리에서 node build/index.js 수동으로 실행하세요.
   • 서버가 성공적으로 시작되면 이 터미널을 열어둔 채로 Claude를 사용하세요.
2. 구성을 확인하세요 :
   • claude_desktop_config.json 의 절대 경로가 시스템에 맞는지 확인하세요.
   • Windows 경로에 이중 백슬래시( \\ )를 사용했는지 다시 한 번 확인하세요.
   • 파일 시스템의 루트에서 전체 경로를 사용하고 있는지 확인하세요.
3. 자동 시작 옵션을 시도해 보세요 .
   • "자동 시작 스크립트 설정" 섹션에 설명된 대로 운영 체제에 대한 자동 시작 스크립트를 설정하세요.
   • 이렇게 하면 필요할 때 서버가 항상 실행되도록 할 수 있습니다.

브라우저가 자동으로 열리지 않습니다

인증 중 브라우저가 자동으로 열리지 않으면 수동으로 http://127.0.0.1:8888/login 방문하세요.

인증 오류

Spotify 개발자 대시보드에서 리디렉션 URI를 올바르게 구성했는지 확인하세요: http://127.0.0.1:8888/callback

서버 시작 오류

다음 사항을 확인하세요.

• 환경 변수는 claude_desktop_config.json 또는 실행 스크립트에서 올바르게 구성되었습니다.
• Node.js가 설치되어 호환됩니다(v16+)
• 필수 포트(8888)가 사용 가능하며 방화벽에 의해 차단되지 않습니다.
• 지정된 위치에서 스크립트를 실행할 수 있는 권한이 있습니다.

Claude에 도구가 나타나지 않음

인증 후 Claude에 Spotify 도구가 나타나지 않는 경우:

• 인증에 성공한 후 Claude Desktop을 다시 시작했는지 확인하세요.
• MCP 통신 오류가 있는지 Claude Desktop 로그를 확인하세요.
• MCP 서버 프로세스가 실행 중인지 확인하세요(확인하려면 수동으로 실행하세요)
• MCP 서버가 Claude Desktop MCP 레지스트리에 올바르게 등록되었는지 확인하세요.

서버가 실행 중인지 확인

서버가 실행 중인지 확인하려면:

• Windows : 작업 관리자를 열고 "세부 정보" 탭으로 이동하여 "node.exe"를 찾으세요.
• macOS/Linux : 터미널을 열고 ps aux | grep node 실행합니다.

서버가 실행 중이 아닌 경우 수동으로 시작하거나 자동 시작 방법을 사용하세요.

테스트

이 프로젝트에는 코드 품질과 기능을 보장하기 위한 자동화된 테스트가 포함되어 있습니다. 테스트 모음은 TypeScript를 지원하는 Jest를 사용하며 다음 내용을 다룹니다.

• Zod 스키마 검증 - 모든 입력 스키마가 올바르게 검증되어 데이터가 검증됩니다.
• Spotify API 상호 작용 - API 요청 처리 및 오류 처리 테스트
• MCP 서버 기능 - 도구의 적절한 등록 및 실행을 보장합니다.

테스트 실행

먼저, 모든 개발 종속성이 설치되었는지 확인하세요.

모든 테스트를 실행하려면:

특정 테스트 파일을 실행하려면:

ESM 모듈에서 문제가 발생하는 경우 Node.js v16 이상을 사용하고 있는지 확인하고 package.json에 구성된 대로 NODE_OPTIONS 환경 변수에 --experimental-vm-modules 플래그가 포함되어 있는지 확인하세요.

테스트 구조

• tests/schemas.test.ts : 입력 검증 스키마에 대한 테스트
• tests/spotify-api.test.ts : Spotify API 상호 작용에 대한 테스트
• tests/server.test.ts : MCP 서버 기능에 대한 테스트

새로운 테스트 추가

새로운 기능을 추가할 때 해당 테스트를 포함하세요.

1. 새로운 스키마의 경우 schemas.test.ts 에 유효성 검사 테스트를 추가합니다.
2. Spotify API 함수의 경우 spotify-api.test.ts 에 테스트를 추가하세요.
3. MCP 도구의 경우 server.test.ts 에 테스트를 추가하세요.

모든 테스트는 Jest와 TypeScript의 ESM 모듈 형식을 사용하여 작성해야 합니다.

보안 참고 사항

• 클라이언트 ID와 클라이언트 비밀번호를 절대 공유하지 마세요.
• 이제 액세스 토큰은 세션과 여러 인스턴스 간의 지속성을 활성화하기 위해 사용자의 홈 디렉토리인 ~/.spotify-mcp/tokens.json 에 저장됩니다.
• 사용자 데이터는 디스크에 저장되지 않습니다.

애플리케이션 액세스 취소

보안상의 이유로 다음과 같은 경우 Spotify 계정에 대한 애플리케이션의 액세스 권한을 취소할 수 있습니다.

• 더 이상 이 통합을 사용하지 않습니다.
• 무단 접근이 의심됩니다
• 인증 문제를 해결하고 있습니다

접근 권한을 취소하려면:

1. Spotify 계정 페이지 로 이동하세요
2. 메뉴에서 "앱"으로 이동합니다.
3. "MCP Claude Spotify"(또는 앱에 선택한 이름)를 찾으세요.
4. "액세스 권한 제거"를 클릭하세요

이렇게 하면 모든 액세스 토큰과 새로 고침 토큰이 즉시 무효화됩니다. 다음에 auth-spotify 명령을 사용할 때 애플리케이션을 다시 인증해야 합니다.

기여하다

여러분의 참여를 환영합니다! 다음 지침을 따르세요.

개발 워크플로

1. 저장소를 포크하세요
2. 기능 브랜치를 생성합니다( git checkout -b feature/amazing-feature )
3. 변경 사항을 만드세요
4. 테스트를 실행하여 통과하는지 확인합니다( npm test )
5. 변경 사항을 커밋하세요( git commit -m 'Add some amazing feature' )
6. 브랜치에 푸시( git push origin feature/amazing-feature )
7. 풀 리퀘스트 열기

코드 스타일 가이드라인

이 프로젝트는 다음과 같은 코딩 표준을 따릅니다.

• 엄격한 유형 검사를 통해 TypeScript를 사용하세요
• ESM 모듈 형식을 따르세요
• 들여쓰기에는 공백 2개를 사용하세요
• 변수와 함수에는 camelCase를 사용하세요
• 클래스와 인터페이스에는 PascalCase를 사용하세요
• JSDoc 주석이 있는 문서 함수
• 줄 길이를 100자 이하로 유지하세요

프로젝트 구조

이 프로젝트는 다음 구조를 따릅니다.

풀 리퀘스트 프로세스

1. 코드가 스타일 가이드라인을 따르는지 확인하세요.
2. 필요한 경우 문서를 업데이트하세요
3. 새로운 기능에 대한 테스트 추가
4. 모든 테스트가 통과되었는지 확인하세요
5. 귀하의 PR은 유지 관리자에 의해 검토됩니다.

관련 링크

• 모델 컨텍스트 프로토콜
• Spotify 웹 API 문서
• 클로드 데스크탑

특허

이 프로젝트는 Mozilla Public License 2.0에 따라 라이선스가 부여되었습니다. 자세한 내용은 LICENSE 파일을 참조하세요.