🎵 Discogs MCP Server

Мощный Model Context Protocol (MCP) сервер, который позволяет AI-ассистентам взаимодействовать с вашей личной музыкальной коллекцией Discogs. Построен на Cloudflare Workers с использованием официального Cloudflare Agents SDK и @modelcontextprotocol/sdk.

✨ Возможности

• 🔐 Безопасная OAuth-аутентификация: Подключайте свой аккаунт Discogs безопасно

• 🧠 Интеллектуальное сопоставление настроения: Переводите эмоции в музыку («нежный», «энергичный», «воскресный вечер»)

• 🔍 Продвинутый поисковый интеллект: Многостратегический поиск с OR-логикой и оценкой релевантности

• 📊 Аналитика коллекции: Всесторонняя статистика и аналитика о вашей музыке

• 🎯 Контекстные рекомендации: Умные предложения на основе настроения, жанра и схожести

• ⚡ Edge-вычисления: Глобальные ответы с низкой задержкой через Cloudflare Workers

• 🗂️ Умное кэширование: Интеллектуальное кэширование на основе KV для оптимальной производительности

• 🔄 Фоновая синхронизация коллекции: Задача каждые 6 часов сохраняет снимок вашей коллекции в KV, поэтому поиск отвечает из снимка, а не перелистывает Discogs при каждом вызове

Related MCP server: 1001 Albums Generator MCP

⚠️ Это не общий сервис

discogs-mcp.com — это личный экземпляр сопровождающего. Он привязан к одному аккаунту Discogs и вернёт 403 для любого другого пользователя.

Почему? Лимит скорости API Discogs (60 запросов в минуту, считается по исходному IP) слишком тесен, чтобы делить его между пользователями. Один активный запрос коллекции от одного пользователя может его насытить. Вместо того чтобы запускать сломанный мультитенантный сервис, каждый пользователь разворачивает свой собственный Worker со своими учётными данными Discogs API.

Хорошая новость: развернуть собственную копию несложно, она работает на бесплатном тарифе Cloudflare Workers и занимает около 10 минут. См. Самозапуск ниже.

🚀 Самозапуск

Самый быстрый путь — кнопка Deploy to Cloudflare выше. Она клонирует этот репозиторий в ваш аккаунт GitHub, создаёт пространства имён KV и Durable Object в вашем аккаунте Cloudflare, запрашивает три секрета и настраивает Workers Builds, чтобы будущие пуши в ваш форк автоматически переразвёртывались.

1. Зарегистрируйте приложение разработчика Discogs

Перейдите на discogs.com/settings/developers → Create an Application. Назовите его как угодно; Callback URL пока может быть заглушкой (вы вернётесь и установите его после развёртывания Worker). Сохраните Consumer Key и Consumer Secret — вы вставите их на следующем шаге.

2. Нажмите кнопку

При появлении запроса вставьте:

После завершения развёртывания Cloudflare покажет URL вашего Worker — что-то вроде https://discogs-mcp.<ваш-поддомен>.workers.dev. Конечная точка MCP — /mcp.

3. Обновите callback URL вашего приложения Discogs

Вернитесь к вашему приложению Discogs и установите Callback URL на:

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

4. (Необязательно, но рекомендуется) Ограничьте экземпляр вашим собственным пользователем Discogs

По умолчанию любой, кто обнаружит URL вашего Worker, может пройти аутентификацию и потреблять ваш бюджет лимита скорости Discogs. Чтобы ограничить доступ, отредактируйте wrangler.toml в вашем форке и установите ALLOWED_DISCOGS_USER_ID в разделе [vars]:

[vars]
# Single user
ALLOWED_DISCOGS_USER_ID = "123456"

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

Найдите свой числовой ID, посетив https://api.discogs.com/users/<ваше-имя-пользователя> и посмотрев поле id. Запушьте изменение — Workers Builds переразвернётся автоматически.

5. Подключите ваш MCP-клиент

Замените https://your-worker.workers.dev ниже на ваш собственный URL.

Claude Desktop — Настройки → Интеграции → Добавить интеграцию → 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 (тестирование):

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

Ручное развёртывание (альтернатива)

Если вы предпочитаете пропустить кнопку — например, вам нужен полностью локальный клон или вы находитесь в аккаунте Cloudflare, где кнопка не работает:

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

Затем выполните шаги 3–5 выше (callback URL, необязательный список разрешённых, подключение MCP-клиента).

Необязательно: маршрутизация вызовов Discogs через ваш собственный IP

Discogs ограничивает по исходному IP, а исходящие запросы Worker покидают общие исходящие IP Cloudflare, поэтому другие Worker, обращающиеся к Discogs из того же места, съедают ваши 60 запросов в минуту. Это видно, когда первый запрос после часов простоя уже сообщает о низком X-Discogs-Ratelimit-Remaining. Если это мешает, укажите Worker на ретранслятор, который вы запускаете: Cloudflare Tunnel к любой постоянно включённой машине (домашний Mac, небольшой VPS) с локальным обратным прокси, который пересылает на https://api.discogs.com и устанавливает и Host, и X-Forwarded-Host в api.discogs.com (один cloudflared не может — он перезаписывает X-Forwarded-Host). Поместите приложение Cloudflare Access с политикой сервисного токена перед именем хоста туннеля, затем:

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

Оставьте DISCOGS_RELAY_ORIGIN пустым, чтобы обращаться к Discogs напрямую (по умолчанию). Если ретранслятор недоступен, Worker для этого запроса переключается на прямые вызовы и регистрирует это, так что выключенная машина деградирует до поведения с общим IP, а не до сбоя. Реализация и обоснование: src/rate-limiter/relay.ts.

Размер коллекции и бесплатный тариф

Ограничение бесплатного тарифа, которое здесь важно, — это время CPU: 10 мс на вызов, как для вызовов инструментов, так и для фоновой синхронизации. Синхронизация сохраняет по одной странице за раз, чтобы оставаться в пределах лимита, а создаваемый снимок хранит только те поля, которые нужны для поиска (около 450 байт на релиз). Это с комфортом покрывает коллекции примерно до 2000 релизов. После этого чтение снимка при каждом поиске начинает перегружать бюджет, и коллекция из 4000+ релизов может привести к сбою search_collection или refresh_collection с голой ошибкой выполнения и без сообщения — это среда выполнения завершает вызов, а не ошибка Discogs. Решение — Workers Paid ($5/месяц), который поднимает бюджет до 30 секунд; больше ничего в развёртывании не меняется.

Независимо от тарифа, get_cache_stats сообщает количество элементов снимка и время его получения, а также количество страниц любой выполняющейся синхронизации, так что вы можете видеть, выполняется ли фоновая синхронизация, а не делать выводы по количеству записей в кэше.

🔐 Аутентификация

Этот сервер использует MCP OAuth 2.1 с Discogs в качестве поставщика удостоверений. При первом подключении:

1. Ваш MCP-клиент автоматически открывает окно браузера

2. Авторизуйте приложение на Discogs

3. Вы перенаправляетесь обратно и проходите аутентификацию — без копирования и вставки

4. Ваша сессия сохраняется в течение 7 дней

🛠️ Доступные инструменты

🔓 Публичные инструменты (без аутентификации)

🔐 Инструменты с аутентификацией (требуется вход)

Поиск и обнаружение

Управление коллекцией

Список желаемого

Папки

Пользовательские поля

Диагностика

📚 MCP-ресурсы

Доступ к данным Discogs через стандартизированные URI ресурсов MCP:

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

💬 MCP-промпты

🏗️ Локальная разработка

# 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

Блок [vars] по умолчанию в wrangler.toml оставляет ALLOWED_DISCOGS_USER_ID пустым, поэтому локальная разработка открыта для любого аккаунта Discogs — удобно для тестирования.

🧪 Тестирование

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

Диагностика

ping и server_info сообщают, как трафик Discogs выходит (напрямую или через ретранслятор, описанный выше) и переключился ли ретранслятор на прямые вызовы. Для получения актуального состояния ограничителя скорости — оставшийся бюджет, глубина очереди, статус автоматического выключателя, откаты ретранслятора — установите секрет DEBUG_TOKEN и вызовите GET /debug/budget?token=<DEBUG_TOKEN>; без секрета конечная точка возвращает 404.

🤝 Вклад

1. Форкните репозиторий

2. Создайте ветку для вашей функции (git checkout -b feature/amazing-feature)

3. Зафиксируйте изменения (git commit -m 'Add amazing feature')

4. Отправьте изменения в ветку (git push origin feature/amazing-feature)

5. Откройте Pull Request

📄 Лицензия

Лицензия MIT — см. файл LICENSE для подробностей.

🙏 Благодарности

• Discogs за API музыкальной базы данных

• Model Context Protocol за стандарт

• Cloudflare Workers за платформу