🎵 Discogs MCP 서버

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

✨ 기능

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

• 🧠 지능형 분위기 매핑: 감정을 음악으로 변환 ("차분한", "활기찬", "일요일 저녁 분위기")

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

• 📊 컬렉션 분석: 음악에 대한 종합적인 통계 및 인사이트

• 🎯 컨텍스트 인식 추천: 분위기, 장르 및 유사성에 기반한 스마트 제안

• ⚡ 엣지 컴퓨팅: Cloudflare Workers를 통한 글로벌 저지연 응답

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

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

Related MCP server: navigravity

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

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

이유는 무엇일까요? Discogs API 속도 제한(분당 60회 요청, 소스 IP 기준)은 여러 사용자가 공유하기에는 너무 빡빡합니다. 한 명의 활성 사용자가 컬렉션을 조회하는 것만으로도 제한에 도달할 수 있습니다. 제대로 작동하지 않는 멀티 테넌트 서비스를 운영하는 대신, 각 사용자가 자신의 Discogs API 자격 증명으로 자신의 Worker를 배포합니다.

좋은 소식: 자신만의 복사본을 배포하는 것은 간단하며, Cloudflare Workers 무료 티어에서 실행되며 약 10분이 소요됩니다. 아래 자체 호스팅을 참조하세요.

🚀 자체 호스팅

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

1. Discogs 개발자 앱 등록

discogs.com/settings/developers로 이동 → 애플리케이션 생성. 이름은 아무거나 지정하세요. 콜백 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 — 설정 → 통합 → 통합 추가 → https://your-worker.workers.dev/mcp

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 / Zed / 일반:

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

MCP Inspector (테스트):

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

수동 배포 (대안)

버튼을 사용하지 않으려는 경우 — 예를 들어 완전히 로컬 클론을 원하거나 버튼이 작동하지 않는 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에서 나가므로 동일한 위치에서 Discogs와 통신하는 다른 Worker가 분당 60회 요청을 소비하게 됩니다. 이는 몇 시간 동안 유휴 상태였던 후 첫 번째 요청에서 이미 낮은 X-Discogs-Ratelimit-Remaining 값을 보고할 때 확인할 수 있습니다. 이 문제가 발생하면 Worker를 사용자가 실행하는 릴레이로 지정하세요: 항상 켜져 있는 모든 머신(집에 있는 Mac, 소형 VPS)에 Cloudflare Tunnel을 연결하고, 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

DISCOGS_RELAY_ORIGIN을 비워두면 Discogs를 직접 호출합니다(기본값). 릴레이에 연결할 수 없는 경우 Worker는 해당 요청에 대해 직접 호출로 대체(fallback)하고 이를 기록하므로, 꺼진 머신은 중단 대신 공유 IP 동작으로 저하됩니다. 구현 및 근거: src/rate-limiter/relay.ts.

🔐 인증

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

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

2. Discogs에서 애플리케이션을 승인합니다

3. 다시 리디렉션되어 인증됩니다 — 복사하여 붙여넣을 필요 없음

4. 세션은 7일 동안 지속됩니다

🛠️ 사용 가능한 도구

🔓 공개 도구 (인증 불필요)

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

검색 및 발견

컬렉션 관리

위시리스트

폴더

사용자 정의 필드

진단

📚 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. 풀 리퀘스트를 열어주세요

📄 라이선스

MIT 라이선스 - 자세한 내용은 LICENSE 파일을 참조하세요.

🙏 감사의 말

• Discogs — 음악 데이터베이스 API용

• Model Context Protocol — 표준용

• Cloudflare Workers — 플랫폼용