🎵 Discogs MCP Server

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

✨ Características

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

• 🧠 Mapeo de estados de ánimo inteligente: Traduce emociones en música ("melódico", "enérgico", "vibraciones de domingo por la noche")

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

• 📊 Analíticas de colección: Estadísticas e información completa sobre tu música

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

• ⚡ Computación en el borde: Respuestas globales de baja latencia mediante Cloudflare Workers

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

• 🔄 Sincronización de colección en segundo plano: Un trabajo cada 6 horas mantiene una instantánea de tu colección en KV, de modo que las búsquedas respondan desde la 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 la instancia privada del mantenedor. Está bloqueada a una sola cuenta de Discogs y devolverá un 403 para cualquier otra persona.

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

La buena noticia: desplegar tu propia copia es sencillo, funciona en el nivel gratuito de Cloudflare Workers y toma unos 10 minutos. Consulta Autoalojamiento a continuación.

🚀 Autoalojamiento

El camino más rápido es el botón Deploy to Cloudflare de arriba. Clona este repositorio en tu cuenta de GitHub, aprovisiona los espacios de nombres KV y el Durable Object en tu cuenta de Cloudflare, te solicita los tres secretos y configura Workers Builds para que los futuros envíos a tu fork se redesplieguen automáticamente.

1. Registra una aplicación de desarrollador de Discogs

Ve a discogs.com/settings/developers → Create an Application. Ponle cualquier nombre; la URL de devolución de llamada puede ser un marcador de posición por ahora (volverás a configurarla después de desplegar el Worker). Guarda la Consumer Key y el Consumer Secret — los pegarás a continuación.

2. Haz clic en el botón

Cuando se te solicite, pega:

Después de que el despliegue se complete, Cloudflare muestra la URL de tu Worker — algo como https://discogs-mcp.<tu-subdominio>.workers.dev. El endpoint de MCP es /mcp.

3. Actualiza la URL de devolución de llamada de tu aplicación de Discogs

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

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

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

Por defecto, cualquiera que descubra la URL de tu Worker puede autenticarse y consumir tu presupuesto de límite de tasa de Discogs. Para restringirlo, edita wrangler.toml en tu fork y establece ALLOWED_DISCOGS_USER_ID bajo [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/<tu-nombre-de-usuario> y mirando el campo id. Empuja el cambio — Workers Builds se redespliega automáticamente.

5. Conecta tu cliente MCP

Reemplaza https://your-worker.workers.dev a continuación con tu propia URL.

Claude Desktop — Configuración → Integraciones → Agregar 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 (pruebas):

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

Despliegue manual (alternativa)

Si prefieres omitir el botón — por ejemplo, quieres un clon completamente local o estás en una cuenta de Cloudflare donde el botón no funciona:

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

Luego sigue los pasos 3–5 de arriba (URL de devolución de llamada, lista de permitidos opcional, conecta tu cliente MCP).

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

Discogs limita por IP de origen, y las solicitudes salientes de un Worker salen desde las IPs de salida compartidas de Cloudflare, por lo que otros Workers que hablan con Discogs desde la misma ubicación consumen tus 60 solicitudes por minuto. Puedes verlo cuando una primera solicitud después de horas de inactividad ya reporta un X-Discogs-Ratelimit-Remaining bajo. Si te afecta, apunta el Worker a un relé que ejecutes: un Cloudflare Tunnel a cualquier máquina siempre encendida (un Mac en casa, un VPS pequeño) con un proxy inverso local que reenvíe a https://api.discogs.com y establezca tanto Host como X-Forwarded-Host a api.discogs.com (cloudflared solo no puede, sobrescribe X-Forwarded-Host). Pon una aplicación de Cloudflare Access con una política de token de servicio frente al nombre de host del túnel, luego:

# 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 (el valor predeterminado). Si el relé no es alcanzable, el Worker cae a llamadas directas para esa solicitud y lo registra, de modo que una máquina apagada degrada al comportamiento de IP compartida en lugar de una interrupción. Implementación y justificación: src/rate-limiter/relay.ts.

Tamaño de colección y el plan gratuito

El límite del plan gratuito que importa aquí es el tiempo de CPU: 10 ms por invocación, tanto para llamadas de herramientas como para la sincronización en segundo plano. La sincronización almacena una página a la vez para mantenerse dentro de eso, y la instantánea que construye conserva solo los campos que la búsqueda necesita (alrededor de 450 bytes por lanzamiento). Eso cubre cómodamente colecciones de hasta aproximadamente 2,000 lanzamientos. Más allá de eso, leer la instantánea en cada búsqueda comienza a agotar el presupuesto, y una colección de 4,000+ puede ver search_collection o refresh_collection fallar 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 eleva el presupuesto a 30 segundos; nada más del despliegue cambia.

Sea cual sea el plan, get_cache_stats reporta el recuento de elementos de la instantánea y el tiempo de obtención, y el recuento de páginas de cualquier sincronización en curso, para que puedas ver si la sincronización en segundo plano está aterrizando en lugar de inferirlo de los recuentos de entradas de caché.

🔐 Autenticación

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

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

2. Autoriza la aplicación en Discogs

3. Se te redirige de vuelta y quedas autenticado — sin necesidad de copiar y pegar

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

🛠️ Herramientas Disponibles

🔓 Herramientas Públicas (Sin Autenticación Requerida)

🔐 Herramientas Autenticadas (Requieren Inicio de Sesión)

Búsqueda y descubrimiento

Gestión de colección

Lista de deseos

Carpetas

Campos personalizados

Diagnóstico

📚 Recursos MCP

Accede a los datos de Discogs mediante URIs de recursos MCP estandarizados:

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

💬 Prompts 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 probar.

🧪 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 (directo o a través del relay descrito anteriormente) y si el relay ha recurrido a llamadas directas. Para el estado en vivo del limitador de velocidad — presupuesto restante, profundidad de la cola, estado del interruptor de circuito, respaldos 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 a la rama (git push origin feature/amazing-feature)

5. Abre un Pull Request

📄 Licencia

Licencia MIT: consulta el archivo LICENSE para más detalles.

🙏 Agradecimientos

• Discogs por la API de la base de datos musical

• Model Context Protocol por el estándar

• Cloudflare Workers por la plataforma