🎵 Discogs MCP Server

AI 어시스턴트가 개인 Discogs 음악 컬렉션과 상호작용할 수 있게 해주는 강력한 Model Context Protocol (MCP) 서버입니다. 공식 Cloudflare Agents SDK와 @modelcontextprotocol/sdk를 사용하여 Cloudflare Workers 위에 구축되었습니다.

✨ 기능

• 🔐 보안 OAuth 인증: Discogs 계정을 안전하게 연결하세요

• 🧠 지능형 무드 매핑: 감정을 음악으로 변환합니다("mellow", "energetic", "Sunday evening vibes")

• 🔍 고급 검색 인텔리전스: OR 로직과 관련성 점수를 사용한 다중 전략 검색

• 📊 컬렉션 분석: 음악에 대한 포괄적인 통계와 인사이트

• 🎯 상황 인식 추천: 무드, 장르, 유사성을 기반으로 한 스마트 추천

• ⚡ 엣지 컴퓨팅: Cloudflare Workers를 통한 전 세계 저지연 응답

• 🗂️ 스마트 캐싱: 최적의 성능을 위한 지능적 KV 기반 캐싱

• 🔄 백그라운드 컬렉션 동기화: 6시간마다 실행되는 작업이 컬렉션의 스냅샷을 KV에 저장하므로, 검색 호출 시 Discogs를 계속해서 페이지 단위로 조회하는 대신 스냅샷에서 응답합니다.

Related MCP server: 1001 Albums Generator MCP

⚠️ 공유 서비스가 아닙니다

discogs-mcp.com은 관리자의 개인 인스턴스입니다. 단일 Discogs 계정에 고정되어 있으며, 다른 사용자에게는 403 오류를 반환합니다.

이유는 무엇일까요? Discogs API 속도 제한(분당 60회 요청, 출발지 IP당 집계)은 여러 사용자가 함께 사용하기에는 너무 빡빡합니다. 한 사용자의 활성 컬렉션 쿼리 하나 만으로도 이 제한을 채울 수 있습니다. 제대로 작동하지 않는 다중 테넌트 서비스를 운영하는 대신, 각 사용자는 자신의 Discogs API 자격 증명을 사용하여 자신만의 Worker를 배포합니다.

좋은 소식: 직접 복사본을 배포하는 것은 간단하며, Cloudflare Workers 무료 요금제에서 실행되고 약 10분밖에 걸리지 않습니다. 아래 자체 호스팅을 참조하세요.

🚀 자체 호스팅

가장 빠른 방법은 위의 Deploy to Cloudflare 버튼입니다. 이 버튼은 이 저장소를 GitHub 계정에 복제하고, Cloudflare 계정에 KV 네임스페이스와 Durable Object를 프로비저닝하며, 세 개의 시크릿을 입력하도록 안내하고, Workers Builds를 설정하여 이후 포크에 대한 푸시가 자동으로 재배포되도록 합니다.

1. Discogs 개발자 앱 등록

discogs.com/settings/developers로 이동 → Create an Application을 클릭하세요. 이름은 아무거나 지정 가능합니다. Callback URL은 일단 임시 값으로 채워두면 됩니다(Worker 배포 후 다시 설정하러 오게 됩니다). Consumer Key와 Consumer Secret을 저장해 두세요. 다음 단계에서 이 값들을 붙여넣게 됩니다.

2. 버튼 클릭

안내에 따라 다음 사항을 붙여넣으세요:

배포가 완료된 후 Cloudflare에서 Worker URL(예: https://discogs-mcp.<your-subdomain>.workers.dev)을 표시합니다. MCP 엔드포인트는 /mcp입니다.

3. Discogs 앱 콜백 URL 업데이트

Discogs 앱으로 돌아가서 Callback URL을 다음 값으로 설정하세요:

https://discogs-mcp.<your-subdomain>.workers.dev/discogs-callback

4. (선택 사항이지만 권장) 인스턴스를 자신의 Discogs 사용자로 잠그기

기본적으로 Worker URL을 아는 사람은 누구나 인증하고 Discogs 속도 제한을 사용할 수 있습니다. 이를 제한하려면 포크된 저장소의 wrangler.toml에서 [vars] 아래에 ALLOWED_DISCOGS_USER_ID를 설정하세요:

[vars]
# Single user
ALLOWED_DISCOGS_USER_ID = "123456"

# Or a comma-separated list for multiple users
ALLOWED_DISCOGS_USER_ID = "123456,789012,345678"

https://api.discogs.com/users/<your-username>를 방문하여 id 필드를 확인하면 숫자 ID를 찾을 수 있습니다. 변경 내용을 푸시하면 Workers Builds는 자동으로 재배포됩니다.

5. MCP 클라이언트 연결

아래의 https://your-worker.workers.dev를 자신의 URL로 바꾸세요.

Claude Desktop — Settings → Integrations → Add Application → https://your-worker.workers.dev/mcp

Clome: (이름 "Claude Code"이라 두 번?).

Let’s correct above. Actually: "Claude Code"? There was "Claude Code". We'll use "Claude Code":

Claude Code:

claude mcp add --transport http discogs https://your-worker.workers.dev/mcp

Windsurf (~/.codeium/windsurf/mcp_config.json):

{
  "mcpServers": {
    "discogs": {
      "serverUrl": "https://your-worker.workers.dev/mcp"
    }
  }
}

Continue.dev / Zel / Gemini: maybe "Continue.dev / Zed / Generic:" preserve. Use "Continue.dev / Zed / Generic:"

{
  "mcpServers": {
    "discogs": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://your-worker.workers.dev/mcp"]
    }
  }
}

MCP Inspector (testing):

npx @modelcontextprotocol/inspector https://your-worker.workers.dev/mcp

수동 배포 (대안)

버튼을 쓰기 보다, 예를 들어 완전한 로컬 클론을 원하거나 버튼이 작동하지 않는다는 Clife Cloudflare 계정인 경우:

git clone https://github.com/rianvdm/discogs-mcp.git
cd discogs-mcp
npm install

# Create the two KV namespaces and copy the returned IDs into wrangler.toml
# (replace the empty `id = ""` values under the top-level [[kv_namespaces]] blocks)
wrangler kv namespace create MCP_SESSIONS
wrangler kv namespace create OAUTH_KV

# Set the three secrets
wrangler secret put DISCOGS_CONSUMER_KEY
wrangler secret put DISCOGS_CONSUMER_SECRET
wrangler secret put JWT_SECRET

# Deploy
npm run deploy

그러면 위의 3~5단계(콜백 URL, 선택적 허용 목록, MCP 클라이언트 연결)를 따르면 됩니다.

선택 사항: Discogs 호출을 자체 IP를 통해 라우팅하기

Discogs는 소스 IP별로 요청을 제한합니다. Worker의 아웃바운드 요청은 Cloudflare의 공유 이그레스 IP에서 나가므로, 같은 위치에서 다른 Worker가 Discogs와 통신할 때도 분당 60회 요청을 소비하게 됩니다. 이 현상은 수시간 동안 유휴 상태 후 첫 요청에서 이미 낮은 X-Discogs-Ratelimit-Remaining 값이 보고될 때 나타납니다. 문제가 된다면 Worker를 직접 운영하는 릴레이로 안내하세요: Cloudflare Tunnel을 통해 항상 켜져 있는 모든 머신(집의 Mac, 작은 VPS 등)에 연결하고, 그 머신에서 https://api.discogs.com으로 포워딩하고 Host와 X-Forwarded-Host를 모두 api.discogs.com으로 설정하는 로컬 리버스 프록시를 실행하십시오(cloudflared는 X-Forwarded-Host를 덮어쓰므로 단독으로 불가능). 그런 다음 터널 호스트림 앞에 서비스 토큰 정책이 포함된 Cloudflare Access 애플리케이션을 배치하고:

# wrangler.toml: DISCOGS_RELAY_ORIGIN = "https://relay.example.com"
wrangler secret put RELAY_ACCESS_CLIENT_ID
wrangler secret put RELAY_ACCESS_CLIENT_SECRET

API Discogs에 직접 호출하려면 DISCOGS_RELAY_ORIGIN을 비워 두세요(기본값). 릴리가 연결할 수 없으면 이 요청을 직접 호출로 대체하고 로그를 남기므로, 전원이 꺼진 컴퓨터는 완전한 중단이 아니라 공유 IP 동작으로 대체됩니다. 구현 및 근거: src/rate-limiter/relay.ts.

컬렉션 크기와 무료 요금제

여기서 중요한 무료 요금제 제한은 CPU 시간입니다: 도구 호출과 백그라운드 동기화 모두 호출 실행당 10ms입니다. 이 제한 안에 있도록 동기화는 한 번에 한 페이지씩 저장하고, 생성하는 스냅샷에는 검색에 필요한 필드만 보관합니다(릴리스당 약 450바이트). 이는 약 2,000개 릴리스까지 충분히 수용합니다. 그보다 큰 컬렉션은 모든 검색에서 스냅샷을 읽는 것만으로도 예산이 부담되며, 컬렉션이 4,000개 이상인 경우 search_collection 또는 refresh_collection이 일반 실행 오류(메시지 없음)와 함께 실패할 수 있습니다. 이는 Disk에서 오류가 아니라 런타임이 호출을 종료시키는 것입니다. 해결책은 Workers 유료 요금제(월 $5)로 전환하는 것이며, 이렇게 하면 예산이 초당 30초까지 늘어납니다. 배포 형태의 다른 부분은 바뀌지 않습니다.

요금제와 무관하게 get_cache_stats는 스냅샷의 항목 수와 가져온 시간, 그리고 실행 중인 동기화의 페이지 수를 보고하므로, 캐시 항목 수만으로 추론하지 않고 백그라운드 동기화가 제대로 이루어지는지 직접 확인할 수 있습니다.

🔐 인증 방인

이 서버는 Discogs를 ID 제공자로 사용하는 MCP OAuth 2.1을 사용합니다. 처음 연결하면:

1. MCP 클라이언트가 자동으로 브r우저 창 Web 엽니다.

2. Discogs에서 응용 프로그램을 승인합니다.

3. 인증 후 다시 redirect됩니다 — 복사-붙여넣기 없이 실행됩니다.

4. 세션이 7day 동안 유지됩니다.

🛠️ 사용 가능한 도구

🔓 공용 도구 (인증 필요 없음)

🔐 인증 필요 도구 (로그인 필요)

검색 및 발견

컬렉션 관리

위시리스트

폴더

사용자 지정 필드

진단

📚 MCP 리소스

표준 MCP 리소스 URI를 통해 Discogs 데이터에 접근합니다:

discogs://collection             # Complete collection (JSON)
discogs://release/{id}           # Specific release details
discogs://search?q={query}       # Search results

💬 MCP 프롬프트

🏗️ 로컬 개발

# Dev secrets live in .dev.vars (gitignored); the same Discogs app is fine for dev
cp .dev.vars.example .dev.vars   # then fill in DISCOGS_CONSUMER_KEY, DISCOGS_CONSUMER_SECRET, JWT_SECRET

# Run the Worker locally
npm run dev

# Test with MCP Inspector
npx @modelcontextprotocol/inspector http://localhost:8787/mcp

wrangler.toml의 기본 [vars] 블록은 ALLOWED_DISCOGS_USER_ID를 비워 두므로, 로컬 개발 환경은 모든 Discogs 계정에 개방되어 있습니다 — 테스트에 편리합니다.

🧪 테스트

npm test              # vitest in watch mode (runs in workerd via @cloudflare/vitest-pool-workers)
npx vitest run        # one pass, then exit
npm run lint          # ESLint; CI runs lint, test, and a dry-run build

진단

ping과 server_info는 Discogs 트래픽이 어떻게 나가는지(직접 또는 위에서 설명한 릴레이를 통해서)와 릴레이가 직접 호출로 폴백했는지 여부를 보고합니다. 속도 제한기의 실시간 상태(남은 예산, 큐 깊이, 서킷 브레이커 상태, 릴레이 폴백)를 확인하려면 DEBUG_TOKEN 시크릿을 설정하고 GET /debug/budget?token=<DEBUG_TOKEN>을 호출하세요. 시크릿이 없으면 엔드포인트는 404를 반환합니다.

🤝 기여하기

1. 저장소를 포크하세요

2. 기능 브랜치를 생성하세요 (git checkout -b feature/amazing-feature)

3. 변경 사항을 커밋하세요 (git commit -m 'Add amazing feature')

4. 브랜치에 푸시하세요 (git push origin feature/amazing-feature)

5. Pull Request를 열어 주세요

📄 라이선스

MIT License - 자세한 내용은 LICENSE 파일을 참조하세요.

🙏 감사의 말

• Discogs 뮤직 데이터베이스 API를 제공해 주셔서 감사합니다

• Model Context Protocol 표준을 제공해 주셔서 감사합니다

• Cloudflare Workers 플랫폼을 제공해 주셔서 감사합니다