🎵 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

⚠️ 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, per registered app) 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:

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).

🔐 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)

🔐 Authenticated Tools (Requires Login)

Search & discovery

Collection management

Folders

Custom fields

Diagnostics

📚 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

🏗️ Local Development

# Set dev secrets (same Discogs app is fine for dev)
wrangler secret put DISCOGS_CONSUMER_KEY
wrangler secret put DISCOGS_CONSUMER_SECRET
wrangler secret put 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              # Run all tests
npm test -- --watch  # Run tests in watch mode

🤝 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