🎵 Discogs MCP Server

Ein leistungsstarker Model Context Protocol (MCP) Server, der KI-Assistenten befähigt, mit Ihrer persönlichen Discogs-Musiksammlung zu interagieren. Basierend auf Cloudflare Workers mit dem offiziellen Cloudflare Agents SDK und @modelcontextprotocol/sdk.

✨ Funktionen

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

• 🧠 Intelligente Stimmungszuordnung: Übersetzen Sie Emotionen in Musik ("sanft", "energiegeladen", "Sonntagabend-Vibes")

• 🔍 Erweiterte Suchintelligenz: Mehrfachstrategie-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: Weltweit niedrige Latenz durch Cloudflare Workers

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

• 🔄 Hintergrund-Synchronisation der Sammlung: Ein 6-stündiger Job speichert eine Momentaufnahme Ihrer Sammlung in KV, sodass Suchanfragen aus der Momentaufnahme beantwortet werden, anstatt bei jedem Aufruf durch Discogs zu blättern

Related MCP server: navigravity

⚠️ Dies ist kein gemeinsamer Dienst

discogs-mcp.com ist die private Instanz des Betreibers. Sie ist auf ein einzelnes Discogs-Konto beschränkt und gibt für alle anderen einen 403 zurück.

Warum? Das Discogs-API-Ratenlimit (60 Anfragen pro Minute, gezählt pro Quell-IP) ist zu knapp, um es mit Benutzern zu teilen. Eine einzige aktive Sammlungsabfrage eines einzelnen Benutzers kann es bereits ausschöpfen. Anstatt einen defekten Mehrbenutzerdienst zu betreiben, stellt jeder Benutzer seinen eigenen Worker mit seinen eigenen Discogs-API-Anmeldedaten bereit.

Die gute Nachricht: Das eigene Deployment ist einfach, läuft auf dem Cloudflare Workers Free-Tarif und dauert etwa 10 Minuten. Siehe Self-Hosting unten.

🚀 Self-Hosting

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, fordert Sie zur Eingabe der drei Geheimnisse auf und richtet Workers Builds ein, sodass zukünftige Pushs in Ihren Fork automatisch neu bereitgestellt werden.

1. Registrieren Sie eine Discogs-Entwickler-App

Gehen Sie zu discogs.com/settings/developers → Create an Application. Geben Sie einen beliebigen Namen ein; die Callback-URL kann vorerst ein Platzhalter sein (Sie kommen später zurück und setzen sie, nachdem der Worker bereitgestellt wurde). Speichern Sie den Consumer Key und Consumer Secret – Sie werden sie im nächsten Schritt einfügen.

2. Klicken Sie auf den Button

Wenn Sie dazu aufgefordert werden, fügen Sie Folgendes 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 findet, 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 betrachten. Übertragen 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 / Generic:

{
  "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

Manuelles Deployment (Alternative)

Wenn Sie den Button überspringen möchten – z. B. weil Sie einen vollständig lokalen Klon wünschen oder sich in einem Cloudflare-Konto befinden, in 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

Führen Sie dann die Schritte 3–5 oben aus (Callback-URL, optionale Whitelist, Verbinden Sie Ihren MCP-Client).

Optional: Discogs-Aufrufe über Ihre eigene IP leiten

Discogs drosselt nach Quell-IP, und die ausgehenden Anfragen eines Workers verlassen Cloudflare über gemeinsame Egress-IPs. Daher verbrauchen andere Worker, die von demselben Standort aus mit Discogs kommunizieren, Ihre 60 Anfragen pro Minute mit. Sie können dies sehen, wenn eine erste Anfrage nach Stunden der Inaktivität bereits einen niedrigen X-Discogs-Ratelimit-Remaining-Wert meldet. Falls es stört, richten Sie den Worker auf ein von Ihnen betriebenes Relay aus: einen Cloudflare Tunnel zu einem ständig eingeschalteten Rechner (ein Mac zu Hause, eine kleine 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). Platzieren Sie eine Cloudflare Access-Anwendung mit einer Service-Token-Richtlinie vor dem 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. Ein ausgeschalteter Rechner führt also zu einem Degradieren auf das Verhalten der gemeinsamen IP, nicht zu einem Ausfall. Implementierung und Begründung: src/rate-limiter/relay.ts.

🔐 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 auf Discogs-Daten über standardisierte MCP-Ressourcen-URIs 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-Verkehr abfließt (direkt oder über das oben beschriebene Relay) und ob das Relay auf direkte Aufrufe zurückgefallen ist. Für den Live-Zustand des Ratenbegrenzers – verbleibendes Budget, Warteschlangentiefe, Schutzschalterstatus, Relay-Fallbacks – setzen Sie ein DEBUG_TOKEN-Geheimnis und rufen Sie GET /debug/budget?token=<DEBUG_TOKEN> auf; ohne das Geheimnis gibt der Endpunkt 404 zurück.

🤝 Beitragen

1. Forken Sie das Repository

2. Erstellen Sie Ihren Feature-Branch (git checkout -b feature/amazing-feature)

3. Committen Sie Ihre Änderungen (git commit -m 'Add amazing feature')

4. Pushen Sie in den Branch (git push origin feature/amazing-feature)

5. Öffnen Sie einen Pull Request

📄 Lizenz

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

🙏 Danksagungen

• Discogs für die Musikdatenbank-API

• Model Context Protocol für den Standard

• Cloudflare Workers für die Plattform