🎵 Discogs MCP Server

Ein leistungsstarker Model Context Protocol (MCP)-Server, der es KI-Assistenten ermöglicht, mit deiner persönlichen Discogs-Musiksammlung zu interagieren. Er läuft auf Cloudflare Workers und nutzt das offizielle Cloudflare Agents SDK sowie @modelcontextprotocol/sdk.

✨ Funktionen

• 🔐 Sichere OAuth-Authentifizierung: Verbinde dein Discogs-Konto sicher

• 🧠 Intelligente Stimmungszuordnung: Übersetzt Emotionen in Musik („mellow“, „energiegeladen“, „Sonntagabend-Vibes“)

• 🔍 Erweiterte Suchintelligenz: Multi-Strategie-Suche mit OR-Logik und Relevanz-Ranking

• 📊 Sammlungs-Analysen: Umfassende Statistiken und Einblicke in deine Musik

• 🎯 Kontextbewusste Empfehlungen: Intelligente Vorschläge basierend auf Stimmung, Genre und Ähnlichkeit

• ⚡ Edge Computing: Weltweite Antworten mit niedriger Latenz dank Cloudflare Workers

• 🗂️ Intelligentes Caching: KV-basiertes Caching für optimale Leistung

• 🔄 Hintergrund-Sync der Sammlung: Ein 6-Stündiger-Job aktualisiert einen Snapshot deiner Sammlung in KV, sodass Suchen auf den Snapshot zugreifen, statt bei jedem Aufruf Discogs zu durchblättern

Related MCP server: 1001 Albums Generator MCP

⚠️ Dies ist kein gemeinsamer Dienst

discogs-mcp.com ist eine private Instanz des Betreuers. Sie ist an ein Discogs-Konto gebunden und liefert für alle anderen eine 403.

Warum? Das Discogs-API-Ratenlimit (60 Anfragen pro Minute, gezählt pro Quell-IP) ist zu knapp, um es über mehrere Nutzer hinweg zu teilen. Eine einzige aktive Sammlungsabfrage kann es bereits ausschöpfen. Statt einen fehlerhaften Multi-Tenant-Dienst zu betreiben, setzt jeder Nutzer einen eigenen Worker mit eigenen Discogs-API-Daten auf. Das funktioniert. Die grüte Nachricht ist zahl: eigenes Deployment ist unkompliziert, läuft im Free-Tier von Cloudflare Workers und dauert ca. 10 Minuten. Siehe dazu Self-Hosting unten.

🚀 Self-Hosting

Der schnellste Weg ist der Deploy to Cloudflare-Button oben. Er klont dieses Repository in dein GitHub-Konto, richtet die KV-Namespaces und den Durable Object in deinem Cloudflare-Konto ein, fragt dich nach den drei Secrets und konkt Workers Builds so ein, dass zukünftige Pushes in deinen Fork automatisch neu bereitfgestellt werden.

1. Discogs-Entwicklerapp registrieren

Gehe zu discogs.com/settings/developers → Create an Application. Gib ihr einen beliebigen Namen; der Callback Writing can be Wille. Die Callback-URL kann noch ein Platoored sein (du setzt sie später nach der Bereitstellung des Workers). Speichere den Consumer Key und das Consumer Secret – du fügst sie beide als Nächstes ein.

2. Button drücken

Füge die folgenden Werte ein:

Nach Abschluss des Deploymentss zeigt Cloudflare dir die Worker-URL – zum Beispiel https://discogs-mcp.<your-subdomain>.workers.dev. The MCP-Endpoint is /mcp.

3. Update the callback URL of your Discogs app

Gehe zurück zu deiner Discogs-App und setze die Callback-URL auf:

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

4. (Optional, empfohlen) Instanz auf deinen eigenen Discogs-Benutzer beschränken

Standardmäßig kann jede Person, die deine Worker-URL entdeckt, sich authentifizieren und dein Discogs-Ratenlimit-Budget verbrauchen. To avoid that, edit wrangler.toml in your Fork and setze ALLOWED_DISCOGS_USER_ID under [vars]:

[vars]
# Single user
ALLOWED_DISCOGS_USER_ID = "123456"

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

Finde deine numerische ID, indem du https://api.discogs.com/users/<your-username> aufrufst und das id-Feld ansiehst. Nachdem du deine Änderung gepusst hast, setzt Workers Builds automatisch neu auf.

5. Verbinde deinen MCP-Client

Ersetze unten die-URL https://your-worker.workers.dev durch deine eigene URL.

Claude Desktop – Einstellungen → Integrationen → Add Integration → Füge 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 / Generic:

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

MCP Inspector (zum Testen):

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

Manuelles Deployment (Alternative)

Falls du den Button lieber überspringen möchtest – zum Beispiel für einen vollständig lokalen Klon oder falls der Button auf deinem Cloudflare-Konto nicht funktioniert:

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

Dann folge den Schritten 3 bis 5 oben (Callback-URL, optische Zulassungsliste, anschließend deinen MCP-Client verbinden).

Optional: Discogs-Aufrufe über eigene IP weiterleiten

Discogs begrenzt An-und die Quell-IP. Da ausgehende Anfragen eines Workers von Cloudflares geteilten Egress-IPs aus gehen, können andere Workers, die von diser selbe IP Discogs anfragen, deine 60 Anfragen pro Minute mit aufbrauchen. Du siehst das, wenn nach ein Stunden Inaktivität die erste Anfrage bereits ein niedriges X-Discogs-Ratelimit-Remaining meldet. Wenn dich das stört, kannst du den Worker auf ein von dir betriebenes Relay zeigen Einen TLS zu richten: ein Cloudflare Tunnel to anyan dauerhaft erreichbaren Rechner (z. B. ein Heim-Mac oder einem kleinen VPS) mit einem lokalen Reverse-Proxy, der Anfragen an https://api.discogs.com weiterleitet und dabei sowohl Host als auch X-Forwarded-Host auf api.discogs.com setzt (cloudflared alleinlem kann das nicht). Lege außerdem eine Cloudflare-Access-Anwendung mit einer Service-Token-Richtlinie vor dem Tunnel-Host. Danach:

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

Lass DISCOGS_RELAY_ORIGIN leer, um Discogs direkt aufzurufen (Standard). Ein unnotartig-cloud? Ist das Relay nicht erreichbar, fällt der Worker für diese Anfrage auf direkte Aufrufe zurück und interniert das, so dass eine ausgeschaltete Maschine nur das Verhalten des geteilten IP-Netzes mit sich bringt und keinen Ausfall. Umsetzung und Begründung: src/rate-limiter/relay.ts.

Sammlungsgröße und der kostenlose Plan

Die relevante Grenze des kostenlosen Plans ist die CPU-Zeit: 10 CPU pro Aufruf und für Hintergrund. Beides. Die Synchronisierung speichert jeweils eine Seite, damit es in diesem Zeitraum bleibt werden kann, und der Snapshot speichert nur die Felder, die die Suche braucht (ca. 450 Bytes pro Release). Damit kannst bequem Sammlungen bis etwa 2.000 Releases abdecken. Darüber hinaus wird das und das Lesen des Snapshots bei jeder Suche seine Budget auslastet werden, bei einer Sammlung von über 4.000 Releases auch während search_collection oder refresh_collection mit einem verdeckten Ausführungsfehler ohne Meldung scheitern. Das ist die Runtime, die den Aufruf beendet, nicht ein Discogs-Fehler. The solution is Workers Paid ($5/month) , das den Budget auf 30 Sekunden erhöht; alles other am Deployment bleibt gleich.

Unabhängig vom Plan, reportieren get_cache_stats die Anzahl der Eintritt e des Snapshots, die Abrufzeit und die Seitenzahl einer laufenden Synchronisierung. Damit kannst du sehen, ob der Hintergrundservice tatsächlich aufbaut, statt, es aus den Cache-Eintrragsnummern abzulesen.

🔐 Authentifizierung

Dieser Server verwendet MCP OAuth 2.1 mit Discogs als Identifikationsanbieter. Bei der erste Verbindung:

1. Dein MCP-Client öffnet, in einem Standardflat das Browser-Fenster

2. Autorisierung für die Discogs-Anwendung

3. Du wirst zurückgeleitet und bist authentifiziert – keine einzelnen Einfügen nötig

4. Deine Sitzung bleibt 7 Tage lang erhalten

🛠️ Tools

🔓 Öffentliche Tools (keine Authentifizierung erforderlich)

🔐 Tools mit Authentifizierung (Anmeldung erforderlich)

Suche & Entdeckung

Sammlungsverwaltung

Wunschliste

Ordner

Benutzerdefinierte Felder

Diagnose

📚 MCP Ressourcen

Greif über standardisierte MCP-Ressourcen-URIs auf Discogs-Daten zu:

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

💬 MCP Prompts

🏗️ Lokale Entwicklung

# 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

Der standardmäßige [vars]-Block in wrangler.toml lässt ALLOWED_DISCOGS_USER_ID leer, sodass die lokale Entwicklung für jedes beliebige Discogs-Konto offen ist – praktisch zum Testen.

🧪 Testen

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

Diagnose

ping und server_info geben an, wie der Discogs-Traffic abgeht (direkt oder über das oben beschriebene Relay) und ob das Relay auf direkte Aufrufe zurückgefallen ist. Für den Live-Status des Rate-Limiters – verbleibendes Budget, Warteschlangentiefe, Circuit-Breaker-Status, Relay-Fallbacks – legst du ein DEBUG_TOKEN-Secret an und rufst GET /debug/budget?token=<DEBUG_TOKEN> auf; ohne das Secret gibt der Endpoint 404 zurück.

🤝 Mitwirken

1. Forke das Repository

2. Erstelle deinen Feature-Branch (git checkout -b feature/amazing-feature)

3. Committe deine Änderungen (git commit -m 'Add amazing feature')

4. Pushe den Branch (git push origin feature/amazing-feature)

5. Öffne einen Pull Request

📄 Lizenz

MIT-Lizenz – siehe LICENSE für Details.

🙏 Danksagungen

• Discogs für die Musikdatenbank-API

• Model Context Protocol für den Standard

• Cloudflare Workers für die Plattform