🎵 Discogs MCP Server

Ein leistungsstarker Model Context Protocol (MCP)-Server, der KI-Assistenten die Interaktion mit Ihrer persönlichen Discogs-Musiksammlung ermöglicht. Gebaut auf Cloudflare Workers mit dem offiziellen Cloudflare Agents SDK und @modelcontextprotocol/sdk.

✨ Funktionen

• 🔐 Sichere OAuth-Authentifizierung: Verbinden Sie Ihr Discogs-Konto sicher

• 🧠 Intelligentes Stimmungs-Mapping: Übersetzen Sie Emotionen in Musik („mellow", „energetic", „Sunday evening vibes")

• 🔍 Fortgeschrittene Suchintelligenz: Mehrstrategien-Suche mit ODER-Logik und Relevanzbewertung

• 📊 Sammlungsanalysen: Umfassende Statistiken und Einblicke in Ihre Musik

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

• ⚡ Edge Computing: Globale Antworten mit geringer Latenz über Cloudflare Workers

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

• 🔄 Hintergrund-Synchronisierung der Sammlung: Ein 6-stündlicher Job hält einen Schnappschuss Ihrer Sammlung in KV, sodass Suchen aus dem Schnappschuss beantwortet werden, anstatt bei jedem Aufruf durch Discogs zu blättern.

Related MCP server: 1001 Albums Generator MCP

⚠️ Dies ist kein gemeinsamer Dienst

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

Warum? Das Discogs-API-Ratenlimit (60 Anfragen pro Minute, gezählt pro Quell-IP) ist zu eng, um es über Benutzer hinweg zu teilen. Eine einzige aktive Sammlungsabfrage eines einzelnen Benutzers kann es bereits sättigen. Anstatt einen defekten Multi-Tenant-Dienst zu betreiben, stellt jeder Benutzer seinen eigenen Worker mit seinen eigenen Discogs-API-Anmeldedaten bereit.

Die gute Nachricht: Das Bereitstellen Ihrer eigenen Kopie ist unkompliziert, läuft auf dem kostenlosen Cloudflare-Workers-Tarif und dauert etwa 10 Minuten. Siehe Selbsthosting unten.

🚀 Selbsthosting

Der schnellste Weg ist der Deploy to Cloudflare-Button oben. Er klont dieses Repository in Ihr GitHub-Konto, richtet die KV-Namespaces und das Durable Object in Ihrem Cloudflare-Konto ein, fragt Sie nach den drei Geheimnissen und richtet Workers Builds ein, sodass zukünftige Pushes an Ihren Fork automatisch neu bereitgestellt werden.

1. Registrieren Sie eine Discogs-Entwickler-App

Gehen Sie zu discogs.com/settings/developers → Create an Application. Benennen Sie es beliebig; die Callback-URL kann vorerst ein Platzhalter sein (Sie kommen zurück und setzen sie, nachdem der Worker bereitgestellt wurde). Speichern Sie den Consumer Key und das Consumer Secret – Sie fügen sie als Nächstes ein.

2. Klicken Sie auf den Button

Wenn Sie dazu aufgefordert werden, fügen Sie ein:

Nach Abschluss der Bereitstellung zeigt Cloudflare Ihre Worker-URL an – etwa https://discogs-mcp.<your-subdomain>.workers.dev. Der MCP-Endpunkt ist /mcp.

3. Aktualisieren Sie die Callback-URL Ihrer Discogs-App

Gehen Sie zurück zu Ihrer Discogs-App und setzen Sie die Callback-URL auf:

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

4. (Optional, aber empfohlen) Sperren Sie Ihre Instanz auf Ihren eigenen Discogs-Benutzer

Standardmäßig kann jeder, der Ihre Worker-URL entdeckt, sich authentifizieren und Ihr Discogs-Ratenlimit-Budget verbrauchen. Um dies einzuschränken, bearbeiten Sie wrangler.toml in Ihrem Fork und setzen Sie ALLOWED_DISCOGS_USER_ID unter [vars]:

[vars]
# Single user
ALLOWED_DISCOGS_USER_ID = "123456"

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

Finden Sie Ihre numerische ID, indem Sie https://api.discogs.com/users/<your-username> besuchen und das Feld id ansehen. Pushen Sie die Änderung – Workers Builds stellt automatisch neu bereit.

5. Verbinden Sie Ihren MCP-Client

Ersetzen Sie https://your-worker.workers.dev unten durch Ihre eigene URL.

Claude Desktop – Einstellungen → Integrationen → Integration hinzufügen → 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 / Allgemein:

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

MCP Inspector (Testen):

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

Manuelle Bereitstellung (Alternative)

Wenn Sie den Button lieber überspringen möchten – zum Beispiel, weil Sie einen vollständig lokalen Klon wünschen oder sich auf einem Cloudflare-Konto befinden, auf dem der Button 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 folgen Sie den Schritten 3–5 oben (Callback-URL, optionale Whitelist, MCP-Client verbinden).

Optional: Discogs-Aufrufe über Ihre eigene IP leiten

Discogs begrenzt nach Quell-IP, und ausgehende Anfragen eines Workers verlassen Cloudflares gemeinsame Egress-IPs, sodass andere Worker, die von derselben Stelle mit Discogs sprechen, in Ihre 60 Anfragen pro Minute einbezogen werden. Sie können dies sehen, wenn eine erste Anfrage nach Stunden der Inaktivität bereits einen niedrigen X-Discogs-Ratelimit-Remaining meldet. Wenn es zwickt, richten Sie den Worker auf ein Relay, das Sie betreiben: einen Cloudflare Tunnel zu einer beliebigen immer eingeschalteten Maschine (ein Heim-Mac, ein kleiner VPS) mit einem lokalen Reverse-Proxy, der an https://api.discogs.com weiterleitet und sowohl Host als auch X-Forwarded-Host auf api.discogs.com setzt (cloudflared allein kann das nicht, es überschreibt X-Forwarded-Host). Stellen Sie eine Cloudflare Access-Anwendung mit einer Service-Token-Richtlinie vor den Tunnel-Hostnamen, dann:

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

Lassen Sie DISCOGS_RELAY_ORIGIN leer, um Discogs direkt aufzurufen (Standard). Wenn das Relay nicht erreichbar ist, fällt der Worker für diese Anfrage auf direkte Aufrufe zurück und protokolliert dies, sodass eine ausgeschaltete Maschine zu gemeinsamem IP-Verhalten degradiert, anstatt zu einem Ausfall zu führen. Implementierung und Begründung: src/rate-limiter/relay.ts.

Sammlungsgröße und der kostenlose Tarif

Das Limit des kostenlosen Tarifs, das hier zählt, ist CPU-Zeit: 10 ms pro Aufruf, sowohl für Tool-Aufrufe als auch für die Hintergrundsynchronisierung. Die Synchronisierung speichert jeweils eine Seite, um innerhalb dieses Limits zu bleiben, und der Schnappschuss, den sie erstellt, enthält nur die Felder, die die Suche benötigt (etwa 450 Bytes pro Veröffentlichung). Das deckt bequem Sammlungen bis zu etwa 2.000 Veröffentlichungen ab. Darüber hinaus beginnt das Lesen des Schnappschusses bei jeder Suche, das Budget zu belasten, und eine Sammlung von 4.000+ kann dazu führen, dass search_collection oder refresh_collection mit einem bloßen Ausführungsfehler und ohne Nachricht fehlschlagen – das ist die Laufzeit, die den Aufruf beendet, kein Discogs-Fehler. Die Lösung ist Workers Paid (5 $/Monat), das das Budget auf 30 Sekunden erhöht; sonst ändert sich nichts an der Bereitstellung.

Unabhängig vom Tarif meldet get_cache_stats die Artikelanzahl und Abrufzeit des Schnappschusses sowie die Seitennummer einer laufenden Synchronisierung, sodass Sie sehen können, ob die Hintergrundsynchronisierung ankommt, anstatt sie aus Cache-Eintragszahlen abzuleiten.

🔐 Authentifizierung

Dieser Server verwendet MCP OAuth 2.1 mit Discogs als Identitätsanbieter. Wenn Sie sich zum ersten Mal verbinden:

1. Ihr MCP-Client öffnet automatisch ein Browserfenster

2. Autorisieren Sie die Anwendung auf Discogs

3. Sie werden zurückgeleitet und authentifiziert – kein Kopieren und Einfügen erforderlich

4. Ihre Sitzung bleibt 7 Tage lang bestehen

🛠️ Verfügbare Tools

🔓 Öffentliche Tools (keine Authentifizierung erforderlich)

🔐 Authentifizierte Tools (Anmeldung erforderlich)

Suche & Entdeckung

Sammlungsverwaltung

Wunschliste

Ordner

Benutzerdefinierte Felder

Diagnose

📚 MCP-Ressourcen

Greifen Sie ü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 Standard-[vars]-Block in wrangler.toml lässt ALLOWED_DISCOGS_USER_ID leer, sodass die lokale Entwicklung für jedes 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 melden, 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-Zustand des Rate-Limiters – verbleibendes Budget, Warteschlangentiefe, Status des Schutzschalters, Relay-Fallbacks – setzen Sie ein DEBUG_TOKEN-Secret und rufen Sie GET /debug/budget?token=<DEBUG_TOKEN> auf; ohne das Secret gibt der Endpunkt 404 zurück.

🤝 Mitwirken

1. Repository forken

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

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

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

5. Pull Request öffnen

📄 Lizenz

MIT-Lizenz – siehe LICENSE-Datei für Details.

🙏 Danksagungen

• Discogs für die Musikdatenbank-API

• Model Context Protocol für den Standard

• Cloudflare Workers für die Plattform