🎵 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: 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을 클릭하세요. 이름은 무엇이든 지정할 수 있습니다. 콜백 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"

숫자 ID를 찾으려면 https://api.discogs.com/users/<your-username>을 방문하여 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는 해당 요청에 대해 직접 호출로 폴백하고 이를 기록하므로, 꺼진 머신은 중단이 아니라 공유 IP 동작으로 저하됩니다. 구현 및 근거: src/rate-limiter/relay.ts.

컬렉션 크기와 무료 플랜

여기서 중요한 무료 플랜의 제한은 CPU 시간입니다: 도구 호출과 백그라운드 동기화 모두에 대해 호출당 10ms입니다. 동기화는 이 한도 내에 머물기 위해 한 번에 한 페이지씩 저장하며, 구축하는 스냅샷은 검색에 필요한 필드만 유지합니다(릴리스당 약 450바이트). 이는 약 2,000개 릴리스까지의 컬렉션을 편안하게 커버합니다. 그 이상이 되면 매 검색마다 스냅샷을 읽는 것이 예산을 압박하기 시작하며, 4,000개 이상의 컬렉션에서는 search_collection 또는 refresh_collection이 메시지 없이 단순 실행 오류로 실패할 수 있습니다 — 이는 Discogs 오류가 아니라 런타임이 호출을 종료하는 것입니다. 해결책은 Workers Paid($5/월)로, 예산을 30초로 올려줍니다. 배포의 다른 부분은 변경되지 않습니다.

플랜에 관계없이 get_cache_stats는 스냅샷의 항목 수와 가져오기 시간, 진행 중인 동기화의 페이지 수를 보고하므로, 캐시 항목 수로 추론하는 대신 백그라운드 동기화가 실제로 이루어지고 있는지 확인할 수 있습니다.

🔐 인증

이 서버는 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 파일을 참조하세요.

🙏 감사의 말

• 음악 데이터베이스 API를 제공하는 Discogs

• 표준을 제공하는 Model Context Protocol

• 플랫폼을 제공하는 Cloudflare Workers