Discogs MCP Server
by nepomusic
README.md
# 🎵 Discogs MCP Server
[](https://github.com/rianvdm/discogs-mcp/releases)
[](https://opensource.org/licenses/MIT)
[](https://www.typescriptlang.org/)
[](https://workers.cloudflare.com/)
[](https://github.com/modelcontextprotocol)
[](https://deploy.workers.cloudflare.com/?url=https://github.com/rianvdm/discogs-mcp)
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](#-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](https://www.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
[](https://deploy.workers.cloudflare.com/?url=https://github.com/rianvdm/discogs-mcp)
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](https://www.discogs.com/settings/developers) 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]`:
```toml
[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**:
```bash
claude mcp add --transport http discogs https://your-worker.workers.dev/mcp
```
**Windsurf** (`~/.codeium/windsurf/mcp_config.json`):
```json
{
"mcpServers": {
"discogs": {
"serverUrl": "https://your-worker.workers.dev/mcp"
}
}
}
```
**Continue.dev / Zed / Generic:**
```json
{
"mcpServers": {
"discogs": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://your-worker.workers.dev/mcp"]
}
}
}
```
**MCP Inspector (testing)**:
```bash
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:
```bash
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:
```bash
# 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](https://developers.cloudflare.com/workers/platform/pricing/) ($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
```bash
# 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
```bash
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](LICENSE) file for details.
## 🙏 Acknowledgments
- [Discogs](https://www.discogs.com/) for the music database API
- [Model Context Protocol](https://modelcontextprotocol.io/) for the standard
- [Cloudflare Workers](https://workers.cloudflare.com/) for the platform