Spotify Playlist MCP

Codex 데스크톱 예약 작업에서 Spotify 재생 목록을 안전하게 관리하기 위한 로컬 STDIO MCP 서버입니다. 소유한 재생 목록을 검사하고, Spotify 트랙을 검색하며, 재생 목록 메타데이터를 업데이트하고, 제한된 계획/적용 워크플로를 통해 트랙을 추가하거나 제거할 수 있습니다.

안전 모델

• Spotify 자격 증명과 안전 설정은 이 프로젝트의 무시된 .env에서만 읽으며, 선택적으로 프로세스 수준의 재정의를 허용합니다.

• OAuth 토큰은 ~/.config/spotify-playlist-mcp/token.json에 파일 모드 0600으로 저장합니다.

• 재생 목록 ID가 SPOTIFY_ALLOWED_PLAYLIST_IDS에 없는 한 모든 쓰기를 거부합니다.

• 인증된 사용자가 재생 목록을 소유하고 있는지 확인합니다.

• 각 계획을 SPOTIFY_MAX_CHANGES_PER_PLAN(기본값 10개 영향 트랙)으로 제한합니다.

• 계획을 현재 Spotify snapshot_id에 바인딩하고, 10분 후 만료시키며, 한 번만 적용할 수 있도록 합니다.

• 첫 쓰기 전에 계획을 소비하므로 부분적으로 적용된 작업이 실수로 재시도될 수 없습니다.

Spotify 갱신 토큰은 현재 인증 후 6개월이 지나면 만료됩니다. spotify_auth_status는 남은 시간을 보고하므로 예약 작업이 재인증이 필요하기 전에 경고할 수 있습니다. Spotify의 갱신 토큰 가이드를 참조하세요.

Related MCP server: MCP Spotify Server

도구

트랙 추가는 끝에 추가됩니다. URI 제거는 일치하는 모든 항목을 제거하며, 영향 개수는 그 동작을 반영합니다. 서버는 의도적으로 대량 교체, 임의 요청, 재생 목록 삭제 또는 계획되지 않은 쓰기를 노출하지 않습니다.

설치 및 확인

source ~/.nvm/nvm.sh
nvm use 24.14.0
npm install
npm test
npm run typecheck
npm run build
npm audit

일회성 Spotify 인증

.env의 리디렉션 URI는 Spotify 대시보드 설정과 정확히 일치해야 합니다. 현재 루프백 콜백은 http://127.0.0.1:3000/auth/callback입니다.

npm run auth

출력된 Spotify URL을 열고 범위를 승인하세요. 명령은 루프백 콜백을 수신하고 토큰을 비공개로 저장합니다. 자격 증명을 노출하지 않고 상태를 확인하세요:

node dist/auth-cli.js --status

Spotify는 현재 6개월마다 재인증을 요구합니다. 액세스 토큰을 갱신해도 갱신 토큰 수명이 연장되지 않기 때문입니다.

Codex 데스크톱 구성

데스크톱 앱, CLI, IDE 확장은 ~/.codex/config.toml을 공유합니다. 예약된 데스크톱 작업은 이 STDIO 서버를 직접 시작할 수 있습니다:

[mcp_servers.spotify-playlists]
command = "/absolute/path/to/node"
args = ["/absolute/path/to/spotify-playlist-mcp/dist/index.js"]
cwd = "/absolute/path/to/spotify-playlist-mcp"
enabled = true
required = true
default_tools_approval_mode = "auto"
tool_timeout_sec = 60

[mcp_servers.spotify-playlists.env]
SPOTIFY_ALLOWED_PLAYLIST_IDS = "replace-with-owned-playlist-id"
SPOTIFY_MAX_CHANGES_PER_PLAN = "10"

[mcp_servers.spotify-playlists.tools.spotify_apply_playlist_plan]
approval_mode = "approve"

MCP 구성을 변경한 후 ChatGPT 데스크톱 앱을 다시 시작하세요. 예약 작업이 로컬 서버를 필요로 할 때 컴퓨터를 켜두고 앱을 실행 중인 상태로 유지하세요. 공식 Codex MCP 구성 및 예약 작업 문서를 참조하세요.

의도한 공개 재생 목록이 존재하고 정확한 ID가 검토될 때까지 SPOTIFY_ALLOWED_PLAYLIST_IDS를 비워 두세요. 여러 ID는 쉼표로 구분할 수 있습니다.

제안된 예약 작업 프롬프트

Use the Spotify playlist MCP to curate only the configured allowlisted playlist.
First check spotify_auth_status and stop with a warning when authorization is missing or due within 14 days.
Inspect the current playlist before searching for candidates.
Follow the playlist's stated audience and description.
Do not remove protected anchor tracks unless the task prompt explicitly names them.
Make no more than the configured change cap.
Create a playlist change plan, report its additions, removals, metadata updates, and warnings, then apply that exact plan only when it matches these rules.
Report the final snapshot ID and Spotify link.

예약하기 전에 이 프롬프트를 수동으로 테스트하세요. 예약 실행은 무인으로 진행되므로 변경 도구가 승인을 요청하도록 구성해서는 안 됩니다.

개발

npm test
npm run typecheck
npm run build

테스트는 인메모리 Spotify 페이크와 인메모리 MCP 전송을 사용합니다. 어떤 테스트도 Spotify를 호출하거나 실제 토큰 파일을 읽지 않습니다.

라이선스

MIT