🎵 Discogs MCP 服务器

一个强大的模型上下文协议（MCP）服务器，使 AI 助手能够与您的个人 Discogs 音乐收藏进行交互。基于 Cloudflare Workers 构建，使用官方 Cloudflare Agents SDK 和 @modelcontextprotocol/sdk。

✨ 功能特性

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

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

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

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

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

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

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

• 🔄 后台收藏同步：每 6 小时执行一次的任务将您的收藏快照存储在 KV 中，因此搜索从快照中应答，而不是每次调用都分页遍历 Discogs

Related MCP server: Discogs MCP Server

⚠️ 这不是共享服务

discogs-mcp.com 是维护者的私有实例。 它锁定在单个 Discogs 账户上，其他人访问将返回 403。

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

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

🚀 自托管

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

1. 注册 Discogs 开发者应用

前往 discogs.com/settings/developers → 创建应用程序。随意命名；回调 URL 暂时可以填写占位符（您将在 Worker 部署后回来设置）。保存消费者密钥和消费者密钥——您将在下一步中粘贴它们。

2. 点击按钮

当提示时，粘贴：

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

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

返回您的 Discogs 应用，将回调 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 发出，因此从同一位置访问 Discogs 的其他 Worker 会消耗您每分钟 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。

收藏大小和免费套餐

免费套餐中与此相关的限制是 CPU 时间：每次调用 10 毫秒，工具调用和后台同步都适用。同步一次只存储一页以保持在限制内，它构建的快照只保留搜索所需的字段（每个版本约 450 字节）。这可以轻松覆盖大约 2,000 个版本的收藏。超过这个数量后，每次搜索读取快照开始占用预算，4,000+ 的收藏可能会看到 search_collection 或 refresh_collection 以无消息的裸执行错误失败 — 这是运行时终止调用，而不是 Discogs 错误。解决方案是 Workers Paid（每月 $5），它将预算提高到 30 秒；部署的其他方面无需更改。

无论使用哪个套餐，get_cache_stats 都会报告快照的项目数量和获取时间，以及任何进行中同步的页数，因此您可以看到后台同步是否成功，而不是从缓存条目数量中推断。

🔐 认证

此服务器使用 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 提供的平台