🎵 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: 1001 Albums Generator MCP

⚠️ 这不是一个共享服务

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

为什么？ Discogs API 的速率限制（每秒 60 次请求，按源 IP 计数）太严，无法在多个用户之间共享。单个用户的一次活跃收藏查询就可能将其占满。与其运行一个看起来不稳定的多租户服务，每个用户都应该使用自己的 Discogs API 凭据部署自己的 Worker。

好消息是：部署你自己的副本并不复杂，可以运行在 Cloudflare Workers 免费套餐上，并且只需要大约 10 分钟。请参阅下方的 自托管。

🚀 自托管

最快的路径是点击上方的 Deploy to Cloudflare 按钮。它会将此同一个仓库克隆到你的 GitHub 账号，在 Cloudflare 账号中预置 KV 命名空间和 Durable Object，提示你输入三个密钥，并设置 Workers Builds，以便以后推送你的 fork 的修改能够自动重新部署。

1. 注册一个 Discogs 开发者应用

前往 discogs.com/settings/developers → 创建应用。名字随意；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 Builders 会自动重新部署。

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 / Generic（通用）:

{
  "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 客户端）进行操作。

可选：将 Discogs 请求路由到你自己拥有的 IP

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 ms，它对工具调用和后台同步同样适用。同步一次只存储若干页，以便保持在限制内，并且它构建的快照只保留搜索所需的字段（每个 release 大约 450 字节）。因此，最多约 2,000 个 release 的收藏量可以舒适地覆盖。超过这个数量后，每次搜索时读取快照可能会开始占用配额，一个 4,000+ release 的收藏可能会看到 search_collection 或 refresh_collection 失败，并出现一个没有消息的执行错误 — 这是运行时终止了调用，而不是 Discogs 的错误。解决方案是 Workers Paid（每月 $5），它会将配额提高到 30 秒；除此之外，部署无需任何更改。

无论在哪个计划上，get_cache_stats 都会报告快照的条目数、获取该快照的时间以及 any pending sync 的页数，所以你不需要通过缓存条目数来推断后台同步是否完成。

🔐 认证

本服务器使用 MCP OAuth 2.1 以及 Discog 作为身份提供方。首次连接时：

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

2. 在 Discogs 上授权该应用

3. 你将被重定向回，并已完成认证 — 无需手动复制粘贴

4. 你的会话持续 7 天

🛠️ 可用工具

🔓 公共工具（无需认证）

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

搜索与发现

收藏管理

愿望清单

文件夹

自定义字段

诊断

📚 MCP Resources

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

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

💬 MCP Prompts

Arguments:

🏗️ 本地开发

# 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 提供的平台