Skip to main content
Glama
Discogs MCP Server

Discogs MCP Server

by nepomusic

🎵 Discogs MCP Server

Version License: MIT TypeScript Cloudflare Workers MCP

Deploy to Cloudflare

一个功能强大的 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: discogs-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. 点击按钮

Deploy to Cloudflare

系统提示时,粘贴:

Secret

Value

DISCOGS_CONSUMER_KEY

来自第 1 步

DISCOGS_CONSUMER_SECRET

来自第 1 步

JWT_SECRET

任意随机字符串 — 例如 openssl rand -hex 32 的输出

部署完成后,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 天

🛠️ 可用工具

🔓 公共工具(无需认证)

工具

描述

ping

测试服务器连接性

server_info

获取服务器信息和能力

auth_status

检查认证状态并获取登录说明

🔐 已认证工具(需要登录)

搜索与发现

工具

描述

search_collection

使用显式音乐流派过滤、情绪感知排序和主版本去重来搜索你的收藏

search_discogs

搜索 Discogs 目录(releases、masters、artists、labels)— 标记你已经拥有的结果

get_release

获取特定 release 的详细信息(tracklist、j格式、labels)

get_collection_stats

查看类型分布、年代分析、格式分布和评分

get_recommendations

按流派、年份、情绪或相似度获取个性化推荐

收藏管理

工具

说明

add_to_collection

将一个 release 添加到文件夹(默认为 Uncategorized)

remove_from_collection

从文件夹中移除特定的 release 实例

move_release

在文件夹之间移动一个 release 实例

rate_release

为 release 打分:0 分(无评分)到 5 星

愿望清单

工具

描述

get_wantlist

列出愿望清单上的 release(分页)

add_to_wantlist

将一个 release 添加到你的愿望清单

remove_from_date

从你的愿望清单中移除一个 release

文件夹

工具

描述

list_folders

列出所有文件夹及其中的 release 数量

create_folder

创建一个新文件夹

edit_folder

重命名一个现有文件夹(系统文件夹除外)

delete_folder

删除一个空文件夹(系统文件夹除外)

自定义字段

工具

描述

list_custom_fields

列出你的收藏中定义的所有自定义字段

edit_custom_field

在特定 release 实例上设置自定义字段的值

诊断

工具

描述

get_cache_stats

查看缓存状态(总条目数、进行中的请求、breakdown)

refresh_collection

立即强制刷新收藏快照,而不是等待

每 6 小时的同步

📚 MCP Resources

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

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

💬 MCP Prompts

Prompt

Description

browse_collection

浏览并探索你收藏中的内容

find_music

在收藏中查找特定的音乐

collection_insights

获取关于收藏的洞察和统计信息

Arguments:

参数

描述

query

要搜索的文本(例如专辑、艺人、曲目)

🏗️ 本地开发

# 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 文件。

🙏 致谢

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables AI assistants to search, manage, and analyze personal Discogs music collections with features like mood-based recommendations, advanced search, and collection analytics.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server that enables AI assistants to interact with a personal Discogs music collection, supporting search, collection management, wantlist, folders, custom fields, and recommendations via Cloudflare Workers.
      MIT
    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables AI assistants to interact with your personal Discogs music collection, including search, mood-aware recommendations, collection analytics, and more.
      13 npm
      MIT
    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables AI assistants to securely connect to a user's personal Discogs music collection for searching, analytics, and mood-aware recommendations.
      MIT