🎵 Discogs MCP Server

一个强大的 Model Context Protocol (MCP) 服务器，让 AI 助手能够与您的个人 Discogs 音乐收藏进行交互。基于 Cloudflare Workers 构建，使用官方的 Cloudflare Agents SDK 和 @modelcontextprotocol/sdk。

✨ 功能特性

• 🔐 安全的 OAuth 认证：安全地连接您的 Discogs 账户

• 🧠 智能情绪映射：将情绪转化为音乐（“柔和”、“充满活力”、“周日晚上的氛围”）

• 🔍 高级搜索智能：多策略搜索，支持 OR 逻辑和相关性评分

• 📊 收藏分析：关于您音乐的全面统计与洞察

• 🎯 上下文感知推荐：基于情绪、流派和相似度的智能建议

• ⚡ 边缘计算：通过 Cloudflare Workers 实现全球低延迟响应

• 🗂️ 智能缓存：基于 KV 的智能缓存，实现最佳性能

• 🔄 后台收藏同步：每 6 小时运行一次的任务，持续将您的收藏快照保存在 KV 中，因此搜索直接基于快照响应，而无需在每次调用时分页请求 Discogs

Related MCP server: navigravity

⚠️ 这不是共享服务

discogs-mcp.com 是维护者的私有实例。 它被锁定到单个 Discogs 账户，对任何其他人都将返回 403。

为什么？Discogs API 速率限制（每分钟 60 次请求，按来源 IP 计数）过于紧张，无法在用户之间共享。单个用户的一次活跃收藏查询就足以使其饱和。与其运行一个不可靠的多租户服务，每个用户部署自己的 Worker，并使用自己的 Discogs API 凭据。

好消息是：部署您自己的副本非常简单，可在 Cloudflare Workers 免费套餐上运行，只需大约 10 分钟。请参阅下方的自托管。

🚀 自托管

最快的路径是上方的 Deploy to Cloudflare 按钮。它会将此仓库克隆到您的 GitHub 账户，在您的 Cloudflare 账户中配置 KV 命名空间和 Durable Object，提示您输入三个密钥，并设置 Workers Builds，这样您未来对 fork 的推送会自动重新部署。

1. 注册 Discogs 开发者应用

前往 discogs.com/settings/developers → Create an Application。名称随意；Callback URL 暂时可以使用占位符（待 Worker 部署后您再回来设置）。保存 Consumer Key 和 Consumer Secret —— 您将在下一步中粘贴它们。

2. 点击按钮

出现提示时，粘贴：

部署完成后，Cloudflare 会显示您的 Worker URL —— 类似于 https://discogs-mcp.<your-subdomain>.workers.dev。MCP 端点为 /mcp。

3. 更新您的 Discogs 应用回调 URL

回到您的 Discogs 应用，将 Callback URL 设置为：

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

4. （可选但推荐）将您的实例锁定到您自己的 Discogs 用户

默认情况下，任何发现您 Worker URL 的人都可以进行身份验证并消耗您的 Discogs 速率限制配额。要加以限制，请在您的 fork 中编辑 wrangler.toml，并在 [vars] 下设置 ALLOWED_DISCOGS_USER_ID：

[vars]
# Single user
ALLOWED_DISCOGS_USER_ID = "123456"

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

访问 https://api.discogs.com/users/<your-username> 并查看 id 字段，即可找到您的数字 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 / 通用：

{
  "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 操作（回调 URL、可选的允许列表、连接您的 MCP 客户端）。

可选：通过您自己的 IP 路由 Discogs 请求

Discogs 按来源 IP 限流，而 Worker 的出站请求从 Cloudflare 的共享出口 IP 发出，因此同一位置的其他 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。

🔐 认证

此服务器使用 MCP OAuth 2.1，以 Discogs 作为身份提供者。当您首次连接时：

1. 您的 MCP 客户端会自动打开浏览器窗口

2. 在 Discogs 上授权该应用程序

3. 您会被重定向回来并完成认证 —— 无需复制粘贴

4. 您的会话将持续 7 天

🛠️ 可用工具

🔓 公共工具（无需认证）

🔐 已认证工具（需要登录）

搜索与发现

收藏管理

愿望清单

文件夹

自定义字段

诊断

📚 MCP 资源

通过标准化的 MCP 资源 URI 访问 Discogs 数据：

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

wrangler.toml 中的默认 [vars] 块将 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. Fork 此仓库

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 作为平台