🎵 Discogs MCP Server

A powerful Model Context Protocol (MCP) server that enables AI assistants to interact with your personal Discogs music collection. Built on Cloudflare Workers using the official Cloudflare Agents SDK and @modelcontextprotocol/sdk.

✨ Features

• 🔐 Secure OAuth Authentication: Connect your Discogs account safely
• 🧠 Intelligent Mood Mapping: Translate emotions into music ("mellow", "energetic", "Sunday evening vibes")
• 🔍 Advanced Search Intelligence: Multi-strategy search with OR logic and relevance scoring
• 📊 Collection Analytics: Comprehensive statistics and insights about your music
• 🎯 Context-Aware Recommendations: Smart suggestions based on mood, genre, and similarity
• ⚡ Edge Computing: Global low-latency responses via Cloudflare Workers
• 🗂️ Smart Caching: Intelligent KV-based caching for optimal performance
• 🔄 Background Collection Sync: A 6-hourly job keeps a snapshot of your collection in KV, so searches answer from the snapshot instead of paging through Discogs on every call

⚠️ This Is Not a Shared Service

discogs-mcp.com is the maintainer's private instance. It's locked to a single Discogs account and will return a 403 for anyone else.

Why? The Discogs API rate limit (60 requests per minute, counted per source IP) is too tight to share across users. One active collection query from a single user can saturate it. Rather than run a broken multi-tenant service, each user deploys their own Worker with their own Discogs API credentials.

The good news: deploying your own copy is straightforward, runs on the Cloudflare Workers free tier, and takes about 10 minutes. See Self-Hosting below.

🚀 Self-Hosting

The fastest path is the Deploy to Cloudflare button above. It clones this repo into your GitHub account, provisions the KV namespaces and Durable Object in your Cloudflare account, prompts you for the three secrets, and sets up Workers Builds so future pushes to your fork redeploy automatically.

1. Register a Discogs developer app

Go to discogs.com/settings/developers → Create an Application. Name it anything; the Callback URL can be a placeholder for now (you'll come back and set it after the Worker is deployed). Save the Consumer Key and Consumer Secret — you'll paste them in next.

2. Click the button

When prompted, paste:

Secret	Value
DISCOGS_CONSUMER_KEY	from step 1
DISCOGS_CONSUMER_SECRET	from step 1
JWT_SECRET	any random string — openssl rand -hex 32 works

After the deploy completes, Cloudflare shows your Worker URL — something like https://discogs-mcp.<your-subdomain>.workers.dev. The MCP endpoint is /mcp.

3. Update your Discogs app callback URL

Go back to your Discogs app and set the Callback URL to:

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

4. (Optional but recommended) Lock your instance to your own Discogs user

By default, anyone who discovers your Worker URL can authenticate and consume your Discogs rate-limit budget. To restrict it, edit wrangler.toml in your fork and set ALLOWED_DISCOGS_USER_ID under [vars]:

[vars]
# Single user
ALLOWED_DISCOGS_USER_ID = "123456"

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

Find your numeric ID by visiting https://api.discogs.com/users/<your-username> and looking at the id field. Push the change — Workers Builds redeploys automatically.

5. Connect your MCP client

Replace https://your-worker.workers.dev below with your own URL.

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 (testing):

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

Manual deploy (alternative)

If you'd rather skip the button — for example, you want a fully local clone or you're on a Cloudflare account where the button doesn't work:

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

Then follow steps 3–5 above (callback URL, optional allowlist, connect your MCP client).

Optional: route Discogs calls through your own IP

Discogs throttles by source IP, and a Worker's outbound requests leave from Cloudflare's shared egress IPs, so other Workers talking to Discogs from the same location eat into your 60 requests a minute. You can see this when a first request after hours of idle already reports a low X-Discogs-Ratelimit-Remaining. If it bites, point the Worker at a relay you run: a Cloudflare Tunnel to any always-on machine (a home Mac, a small VPS) with a local reverse proxy that forwards to https://api.discogs.com and sets both Host and X-Forwarded-Host to api.discogs.com (cloudflared alone can't, it overwrites X-Forwarded-Host). Put a Cloudflare Access application with a service-token policy in front of the tunnel hostname, then:

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

Leave DISCOGS_RELAY_ORIGIN empty to call Discogs directly (the default). If the relay is unreachable the Worker falls back to direct calls for that request and logs it, so a machine that is switched off degrades to the shared-IP behaviour rather than an outage. Implementation and rationale: src/rate-limiter/relay.ts.

Collection size and the free plan

The free plan's limit that matters here is CPU time: 10 ms per invocation, for tool calls and the background sync alike. The sync stores one page at a time to stay inside that, and the snapshot it builds keeps only the fields search needs (about 450 bytes per release). That comfortably covers collections up to roughly 2,000 releases. Past that, reading the snapshot on every search starts to crowd the budget, and a collection of 4,000+ can see search_collection or refresh_collection fail with a bare execution error and no message — that is the runtime terminating the invocation, not a Discogs error. The fix is Workers Paid ($5/month), which raises the budget to 30 seconds; nothing else about the deployment changes.

Whatever the plan, get_cache_stats reports the snapshot's item count and fetch time and the page count of any sync in flight, so you can see whether the background sync is landing rather than inferring it from cache entry counts.

🔐 Authentication

This server uses MCP OAuth 2.1 with Discogs as the identity provider. When you connect for the first time:

1. Your MCP client automatically opens a browser window
2. Authorize the application on Discogs
3. You're redirected back and authenticated — no copy-pasting required
4. Your session persists for 7 days

🛠️ Available Tools

🔓 Public Tools (No Authentication Required)

Tool	Description
ping	Test server connectivity
server_info	Get server information and capabilities
auth_status	Check authentication status and get login instructions

🔐 Authenticated Tools (Requires Login)

Search & discovery

Tool	Description
search_collection	Search your collection with explicit genre filters, mood-aware ranking, and master-level dedup
search_discogs	Search the Discogs-wide catalog (releases, masters, artists, labels) — marks results you already own
get_release	Get detailed information about a specific release (tracklist, formats, labels)
get_collection_stats	View genre breakdown, decade analysis, format distribution, and ratings
get_recommendations	Get personalized recommendations by genre, decade, mood, or similarity

Collection management

Tool	Description
add_to_collection	Add a release to a folder (defaults to Uncategorized)
remove_from_collection	Remove a specific release instance from a folder
move_release	Move a release instance between folders
rate_release	Rate a release from 0 (no rating) to 5 stars

Wantlist

Tool	Description
get_wantlist	List releases on your wantlist (paginated)
add_to_wantlist	Add a release to your wantlist
remove_from_wantlist	Remove a release from your wantlist

Folders

Tool	Description
list_folders	List all folders with release counts
create_folder	Create a new folder
edit_folder	Rename an existing folder (system folders excluded)
delete_folder	Delete an empty folder (system folders excluded)

Custom fields

Tool	Description
list_custom_fields	List all custom fields defined on your collection
edit_custom_field	Set a custom field value on a specific release instance

Diagnostics

Tool	Description
get_cache_stats	View cache performance (total entries, pending requests, breakdown)
refresh_collection	Force a full refresh of the collection snapshot now, instead of waiting for the 6-hourly sync

📚 MCP Resources

Access Discogs data via standardized MCP resource URIs:

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

💬 MCP Prompts

Prompt	Description	Arguments
browse_collection	Browse and explore your collection
find_music	Find specific music in your collection	query
collection_insights	Get insights and statistics about your collection

🏗️ Local Development

# 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

The default [vars] block in wrangler.toml leaves ALLOWED_DISCOGS_USER_ID empty, so local dev is open to any Discogs account — convenient for testing.

🧪 Testing

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

Diagnostics

ping and server_info report how Discogs traffic is leaving (direct, or via the relay described above) and whether the relay has fallen back to direct calls. For the rate limiter's live state — remaining budget, queue depth, circuit-breaker status, relay fallbacks — set a DEBUG_TOKEN secret and call GET /debug/budget?token=<DEBUG_TOKEN>; without the secret the endpoint returns 404.

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• Discogs for the music database API
• Model Context Protocol for the standard
• Cloudflare Workers for the platform