🎵 Discogs MCP Server

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

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

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

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

• 🔍 Умный поиск: многостратегический поиск с логикой OR и оценкой релевантности

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

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

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

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

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

Related MCP server: 1001 Albums Generator MCP

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

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

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

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

🚀 Самостоятельное размещение

Самый быстрый путь — кнопка Deploy to Cloudflare выше. Она клонирует этот репозиторий в ваш аккаунт GitHub, создаёт KV namespaces и 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.<your-subdomain>.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/<your-username> и посмотрев поле id. После изменения запушьте коммит — Workers Builds развернёт изменения автоматически.

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

Замените https://your-worker.workers.dev ниже на адрес вашего Worker.

Claude Desktop — Settings → Integrations → Add Integration → 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, необязательный allowlist, подключение MCP-клиента).

Необязательно: направлять запросы к Discogs через собственный IP-адрес

Discogs ограничивает запросы по IP-адресу источника, а исходящие запросы Worker уходят с общих IP-адресов Cloudflare. Поэтому другие Worker'ы, обращающиеся к Discogs из той же локации, могут расходовать ваши 60 запросов в минуту. Это заметно, когда первый запрос после долгой простоя уже показывает низкий X-:rate-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 байт на релиз). Этого достаточно для коллекций примерно до 2 000 релизов. При больших коллекциях чтение снимка на каждом поиске начинает расходовать бюджет, и у коллекции 4 000+ релизов может возникнуть ошибка выполнения без сообщения — это не ошибка Discogs, а прерывание вызова средой выполнения. Решение — Workers Paid ($5/мес), который повышает потолок до 30 секунд; больше ничего в развёртывании не меняется.

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

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

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

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

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

3. Происходит перенаправление обратно, и вы уже аутентифицированы — копировать и вставлять ничего не нужно

4. Сессия сохраняется на 7 дней

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

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

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

Поиск и владение

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

Wantlist

Папки

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

Диагностика

📚 Ресурсы MCP

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

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 — подробности в файле LICENSE.

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

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

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

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