🎵 Discogs MCP Server

Un potente servidor de Model Context Protocol (MCP) que permite a los asistentes de IA interactuar con tu colección de música personal de Discogs. Construido sobre Cloudflare Workers con el Cloudflare Agents SDK y @modelcontextprotocol/sdk oficiales.

✨ Características

• 🔐 Autenticación OAuth segura: Conecta tu cuenta de Discogs de forma segura

• 🧠 Asignación de emociones inteligente: Traduce emociones en música («tranquilo», «enérgico», «ambiente de domingo por la noche»)

• 🔍 Inteligencia de búsqueda avanzada: Búsqueda multiestrategia con lógica OR y puntuación por relevancia

• 📊 Analítica de colección: Estadísticas y perspectivas completas sobre tu música

• 🎯 Recomendaciones contextuales: Sugerencias inteligentes basadas en estado de ánimo, género y similitud

• ⚡ Edge computing: Respuestas de baja latencia global gracias a Cloudflare Workers

• 🗂️ Caché inteligente: Caché basada en KV para un rendimiento óptimo

• 🔄 Sincronización de colección en segundo plano: Un proceso cada 6 horas mantiene una instantánea de tu colección en KV, de modo que las búsquedas responden desde esa instantánea en lugar de paginar por Discogs en cada llamada

Related MCP server: 1001 Albums Generator MCP

⚠️ Esto no es un servicio compartido

discogs-mcp.com es una instancia privada del mantenedor. Está bloqueada para una única cuenta de Discogs y devolverá un 403 a cualquier otra persona.

¿Por qué? El límite de peticiones de la API de Discogs (60 peticiones por minuto, contadas por IP de origen) es demasiado ajustado para compartirlo entre usuarios. Una única consulta activa a la colección puede saturarlo. En lugar de ofrecer un servicio multiusuario defectuoso, cada usuario despliega su propio Worker con sus propias credenciales de la API de Discogs.

La buena noticia: desplegar tu propia copia es sencillo, funciona en el plan gratuito de Cloudflare Workers y tan solo tarda unos 10 minutos. Consulta Alojamiento propio más abajo.

🚀 Alojamiento propio

El camino más rápido es el botón Deploy to Cloudflare de arriba. Clona este repositorio en tu cuenta de GitHub, configura los namespaces de KV y el Durable Object en tu cuenta de Cloudflare, te pide los tres secretos y activa Workers Builds para que futuros cambios en tu fork se redistribuyan automáticamente.

1. Registra una aplicación de desarrollador de Discogs

Ve a discogs.com/settings/developers → Create an Application. Ponle cualquier nombre; la Callback URL puede ser un marcador provisional (volverás a ella después de que el Worker esté desplegado). Guarda el Consumer Key y el Consumer Secret; los pegarás en el siguiente paso.

2. Haz clic en el botón

Cuando se lo pida, pega lo siguiente:

Después de completar el despliegue, Cloudflare te muestra la URL de tu Worker, algo así como https://discogs-mcp.<your-subdomain>.workers.dev. El endpoint de MCP es /mcp.

3. Actualiza la dirección de callback de tu aplicación Discogs

Vuelve a tu aplicación Discogs y establece la Callback URL como:

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

Actividad este paso sin cerrar sesión.

4. (Opcional pero recomendado) Restringe la instancia a tu propio usuario de Discogs

Por defecto, cualquiera que descubra la URL de tu Worker puede autenticarse y consumir tu cuota de límite de Discogs. Para restringirlo, edita wrangler.toml en tu fork y añade ALLOWED_DISCOGS_USER_ID dentro de [vars]:

[vars]
# Single user
ALLOWED_DISCOGS_USER_ID = "123456"

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

Encuentra tu ID numérico visitando https://api.discogs.com/users/<your-username> y mirando el campo id. Haz el cambio y sube; Workers Builds se redistribuye automáticamente.

5. Conecta tu cliente MCP

Sustituye https://your-worker.workers.dev más abajo por tu propia URL.

Claude Desktop — Configuración → Integraciones → Añadir integración → 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 / Genérico:

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

MCP Inspector (probando):

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

Despliegue manual (alternativa)

Si prefieres evitar el botón — por ejemplo, porque quieres un clon completamente local o porque tu cuenta de Cloudflare no permite el botón —:

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

Después sigue los pasos 3-5 anteriores (URL de callback, lista blanca opcional, conecta tu cliente MCP).

Opcional: enruta las llamadas a Discogs a través de tu propia IP

Discogs limita por IP de origen, y las peticiones salientes de un Worker se realizan desde las IPs compartidas de Cloudflare, así que otros Workers que llamen a Discogs desde la misma ubicación consumen tus 60 peticiones por minuto. Puedes verlo cuando una primera petición después de mucho inactividad ya muestra un X-Discogs-Ratelimit-Remaining bajo. Si te molesta, dirige el Worker hacia un relay controlado por ti: un Cloudflare Tunnel a cualquier máquina siempre encendida (un Mac en casa, un VPS pequeño) con un proxy inverso local que redirija a https://api.discogs.com y establezca Host y X-Forwarded-Host a api.discogs.com (cloudflared por sí solo no puede, porque sobrescribe X-Forwarded-Host). Pon una aplicación de Cloudflare Access con una política de service token delante del hostname del túnel, y después:

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

Deja DISCOGS_RELAY_ORIGIN vacío para llamar a Discogs directamente (por defecto). Si el relay no está disponible, el Worker se retira a llamadas directas para esa petición y lo registra, por lo que una máquina apagada se degrada al comportamiento de IP compartida en lugar de provocar una interrupción del servicio. Implementación y justificación: src/rate-limiter/relay.ts.

Tamaño de la colección y el plan gratuito

El límite del plan gratuito que cuenta aquí es el tiempo de CPU: 10 ms por invocación, tanto en las llamadas de herramientas como en la sincronización en segundo plano. La sincronización almacena una página cada vez para mantenerse dentro de ese límite y la instantánea que construye solo guarda los campos que la búsqueda necesita (unos 450 bytes por lanzamiento). Eso cubre colecciones de hasta 2.000 lanzamientos sin dificultad. A partir de ahí, leer la instantánea en cada búsqueda empieza a acercarse al límite, y una colección de 4.000 o más puede hacer que search_collection o refresh_collection fallen con un error de ejecución desnudo y sin mensaje: eso es el runtime terminando la invocación, no un error de Discogs. La solución es Workers Paid ($5/mes), que sube el presupuesto a 30 segundos; también cambia nada más en el despliegue.

Independientemente del plan, get_cache_stats informa del número de elementos e instantes de descarga de la instantánea y de las páginas de cualquier sincronización en curso, así puedes ver si la sincronización en segundo plano está llegando en lugar de inferirlo a partir de los contadores de la caché.

🔐 Autenticación

Este servidor usa MCP OAuth 2.1 con Discogs como proveedor de identidad. Cuando se conecta por primera vez:

1. Tu cliente MCP abre automáticamente una ventana del navegador

2. Autoriza la aplicación en Discogs

3. Eres redirigido de vuelta y quedas autentificado: no requiere copiar y pegar

4. Tu sesión persiste durante 7 días

🛠️ Herramientas disponibles

🔓 Herramientas públicas (sin autenticación)

🔐 Herramientas autenticadas (requieren inicio)

Búsqueda y descubrimiento

Gestión de colección

Wantlist

Carpetas

Campos personalizados

Diagnóstico

📚 Recursos MCP

Accede a datos de Discogs a través de URIs de recursos MCP estandarizados:

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

💬 Prompts de MCP

🏗️ Desarrollo local

# 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

El bloque [vars] predeterminado en wrangler.toml deja ALLOWED_DISCOGS_USER_ID vacío, por lo que el desarrollo local está abierto a cualquier cuenta de Discogs — conveniente para pruebas.

🧪 Pruebas

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

Diagnósticos

ping y server_info informan cómo sale el tráfico de Discogs (directamente o a través del relay descrito anteriormente) y si el relay ha vuelto a las llamadas directas. Para el estado en tiempo real del limitador de velocidad — presupuesto restante, profundidad de la cola, estado del interruptor de circuito, fallbacks del relay — establece un secreto DEBUG_TOKEN y llama a GET /debug/budget?token=<DEBUG_TOKEN>; sin el secreto, el endpoint devuelve 404.

🤝 Contribuciones

1. Haz un fork del repositorio

2. Crea tu rama de características (git checkout -b feature/amazing-feature)

3. Haz commit de tus cambios (git commit -m 'Add amazing feature')

4. Haz push de la rama (git push origin feature/amazing-feature)

5. Abre un Pull Request

📄 Licencia

Licencia MIT — consulta el archivo LICENSE para ver el details.

🙏 Agradecimientos

• Discogs por la API de la base de datos de música

• Model Context Protocol por el estándar

• Cloudflare Workers por la plataforma