Bandcamp crate digging

bandcamp-mcp

与 Claude 对话，深入探索 Bandcamp：查找唱片公司的艺人阵容，查看某个标签下的新内容，调出专辑曲目列表和价格，还能找出那张合辑第 7 首曲目究竟是谁创作的。bandcamp-mcp 是一个本地 MCP 服务——AI 助手借此访问你机器上的工具——因此任何 MCP 客户端都可以使用它：Claude Desktop、Claude Code、Cursor、VS Code。无需账户，无需 API 密钥，无需配置。

状态：实验性。 尚未达到 1.0，且仍在积极开发：次要版本可能会更改行为或破坏兼容性，补丁版本则不会。仅支持最新版本。

与 Bandcamp 无关联、未获其认可，也未受其赞助。

你可以询问的内容

• “Sacred Bones 的目录里有哪些内容？每张发行作品分别由谁创作？”
• “找出 John Carpenter 的专辑 Cathedral，并读出曲目列表和每首曲目的时长。”
• “显示 drum-bass 标签下的十张新发行作品，然后逐一打开，告诉我各自的唱片公司和发行日期。”
• “那张合辑是由多位艺人创作的吗？告诉我每首曲目分别由谁创作。”
• “这张专辑多少钱？它可以按意愿定价吗？”
• “找到朋友发给我的那个 Bandcamp 链接，并告诉我这位艺人还发行过什么作品。”

答案来自 Bandcamp 自己的公开页面，并在使用时实时获取——助手每调用一次工具，就会发出一个请求。服务只读取内容；它绝不会购买、下载或访问账户，也没有任何途径能向你提供流媒体或下载链接。

安装

npx 就是全部安装步骤：MCP 客户端会按需启动服务，并在下次启动时获取修复。

Claude Code：

claude mcp add bandcamp -- npx -y bandcamp-mcp

Claude Desktop（Settings → Developer → Edit Config），或任何能通过命令启动 stdio 服务的 MCP 客户端：

{
  "mcpServers": {
    "bandcamp": {
      "command": "npx",
      "args": ["-y", "bandcamp-mcp"]
    }
  }
}

Cursor：在 Cursor 中安装， 或将相同的 JSON 代码块添加到 ~/.cursor/mcp.json。

VS Code（Copilot Agent 模式）：在 VS Code 中安装， 或运行 code --add-mcp '{"name":"bandcamp","command":"npx","args":["-y","bandcamp-mcp"]}'。

**Claude Code 插件：**此仓库同时也是一个插件 （.claude-plugin/plugin.json），因此将其列入后即可通过 /plugin 安装。

环境要求及实际测试范围

Node.js 20 或更高版本（推荐使用 22 LTS）；Node 18 已停止维护，而且 MCP SDK 的一个依赖要求 Node 20。每次推送都会在 Node 20、22 和 24 上运行测试套件，然后打包该软件包、将其安装到空项目中，并在 Linux、macOS 和 Windows 上通过 MCP 握手启动，每个 Node 版本都会进行测试。我们不会声称支持其他平台：它们或许也能运行，但尚未有人进行测试。

Bandcamp 本身没有带版本号的 API。服务读取的是 bandcamp.com 当前提供的内容，因此我们每天都会针对实时网站运行冒烟测试（见上方徽章）；工具也可能在毫无预警的情况下开始失效——详见工作原理及可能导致故障的原因。

若要固定版本，请使用 bandcamp-mcp@<version>（例如 npx -y [email protected]）。 未固定版本的 npx -y bandcamp-mcp 会在客户端下次启动时获取修复；固定版本或全局安装的副本则不会（见 已知限制）。

Windows

Windows 上的 GUI MCP 客户端通常无法直接启动 npx，因为它是一个 .cmd 脚本。请用 cmd /c 将其包装起来：

{
  "mcpServers": {
    "bandcamp": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "bandcamp-mcp"]
    }
  }
}

使用 Claude Code：

claude mcp add bandcamp -- cmd /c npx -y bandcamp-mcp

CI 会检查此命令：在 windows-latest 上，package 作业会将打包后的软件包 安装到一个项目中，并通过 MCP 握手（initialize，然后是 tools/list）在该项目中运行 cmd /c npx -y bandcamp-mcp。此时，npx 会找到已安装的副本，而不是下载它，因此这项检查覆盖的是服务在 Windows 上的启动方式，而不是下载过程。

故障排除：“server disconnected” / spawn npx ENOENT

通过 GUI 启动的 MCP 客户端通常会使用精简的 PATH 启动服务，其中不包含 nvm/volta shim，即使在终端中运行 npx -y bandcamp-mcp 没问题也是如此。请全局安装软件包，并在客户端中使用绝对路径：

npm install -g bandcamp-mcp
which node                                         # the "command" below (Windows: where node)
echo "$(npm root -g)/bandcamp-mcp/dist/index.js"   # the "args" entry below

{
  "mcpServers": {
    "bandcamp": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/node_modules/bandcamp-mcp/dist/index.js"]
    }
  }
}

在 Windows 上，JSON 路径中的每个反斜杠都必须加倍，例如 C:\\Users\\you\\AppData\\Roaming\\npm\\node_modules\\bandcamp-mcp\\dist\\index.js。 全局安装不会自动更新：运行 npm install -g bandcamp-mcp@latest 以获取修复。

如果你的网络阻止访问 npm registry

每次客户端启动服务时，npx 都会在 registry.npmjs.org 上查找软件包。如果 registry 被阻止，或只能偶尔访问，请在网络可用时运行一次 npm install -g bandcamp-mcp，并使用上面的绝对路径配置，这样启动时就无需访问 registry。

工作原理及可能出错的原因

Bandcamp 没有公开的目录 API，因此每次调用工具都会实时请求 Bandcamp 自家网站使用的同一组端点：

• bandcamp_search：Bandcamp 搜索框背后的 JSON 端点 (/api/bcsearch_public_api/1/autocomplete_elastic)；
• bandcamp_browse_tag：bandcamp.com/discover 背后的 JSON 端点 (/api/discover/1/discover_web)；
• bandcamp_get_album 和 bandcamp_get_track：公开的发行或曲目页面，主要从其 schema.org JSON-LD 区块读取信息，标签则来自页面标记；
• bandcamp_get_artist：艺人或厂牌的 /music 页面，从其标记中读取信息。

这些都不是已发布、带版本号的 API。Bandcamp 可以随时更改它们，且不另行通知；发生更改后，工具就会停止工作，直到本项目发布修复版本。出现这种情况时，工具会说明原因（“Bandcamp 的响应格式似乎发生了变化”，或提示收到的是机器人检测而非数据），并链接到问题页面。每日冒烟测试（见上方徽章）会使用实时 Bandcamp 页面运行每个工具的客户端代码，并将故障报告到跟踪问题。端点说明见 docs/bandcamp-endpoints.md。

• 仅提供元数据。 发行内容按 slug 标识，而结果架构（src/client/types.ts）中没有流媒体、下载或购买链接的字段，因此 Bandcamp 页面中的签名音频链接不会被传递出去。（自由文本字段由艺人自行撰写，其中可能提及链接。）
• 不缓存或重新发布。 每次调用工具都会实时获取数据，不存储任何内容；结果只会发送到你的 MCP 客户端，不会发送到其他地方。
• 无遥测。 本软件包和 Venut Technologies 均不会收集任何信息；服务器读取、发送和存储的内容列于 PRIVACY.md。 但是，每次调用工具都是从你的设备直接向 Bandcamp 发出的请求；Bandcamp 会看到你的 IP 地址、请求内容及请求时间。请求还会标明来源，其 User-Agent 为 Mozilla/5.0 (compatible; bandcamp-mcp/<version>; +https://github.com/Venut-Technologies/bandcamp-mcp)， 因此看起来不像浏览器访问。
• 设计上保持温和。 同时最多发出 3 个请求，间隔至少 150 ms；超时设为 7 秒；遇到超时、传输层故障（连接重置或套接字关闭、DNS 或 TLS 错误）、5xx 或 429 时重试一次（遵循最长 5 秒的 Retry-After）。只会请求 bandcamp.com 和 *.bandcamp.com 主机：重定向由程序手动跟进（最多 3 次），并会检查每个目标是否属于该列表。

Bandcamp 的 robots.txt 禁止爬虫访问 /api/，这涵盖搜索端点；同时明确允许访问浏览端点。本服务不是爬虫：每次工具调用只会获取一个页面，不跟进链接，也不存储任何内容。对此的解读、反对意见，以及若 Bandcamp 提出异议就修改或移除工具的承诺，均记录在 CONTRIBUTING.md。

代码库（而非 npm 软件包）包含从 Bandcamp 捕获的页面和 API 响应，作为测试样本；其中签名流媒体和下载 URL 已删去，身份信息和自由文本已替换为虚构内容，并且每个页面都已精简至解析器读取的标记。

发现 Bug，或对滥用行为有疑虑？请提交问题： https://github.com/Venut-Technologies/bandcamp-mcp/issues

安全问题请改为私下发送至 [email protected]；详见 SECURITY.md。

工具

工具	输入	返回内容
bandcamp_search	query（1–200 个字符）；type：all（默认）、album、artist、track 或 label	按排名排序的匹配结果，每项为 {type, name, artist, slug}。每个结果中的 Bandcamp is_label 标记用于区分艺人和厂牌。
bandcamp_get_album	slug，例如 johncarpentermusic/album/cathedral	标题、艺人、发行日期、厂牌、标签、描述、数字版价格（priceText 是最低价格，另有 priceCurrency；以及 isNameYourPrice），以及曲目列表：每首曲目都包含其艺人（合辑）、排序位置、时长和 slug。
bandcamp_get_artist	slug：艺人或厂牌的子域名，例如 sacredbonesrecords	名称、所在地、简介和作品目录：最多 100 条 {title, slug, type, artist}（在厂牌页面中，artist 是每个发行作品对应的艺人）。discographyTotal 统计所有发行作品；discographyTruncated 表示是否有作品被截去。不包含标签。
bandcamp_get_track	slug，例如 johncarpentermusic/track/primeval	任意曲目页面，无论是专辑中的曲目还是独立单曲：标题、艺人、时长、标签、描述，以及所属专辑 album {title, slug}（对于独立单曲，专辑为曲目本身的标题，且 slug: null；如果页面完全没有列出专辑，则为 null）。
bandcamp_browse_tag	tag（可选）：Bandcamp 标签 slug，例如 ambient、drum-bass 或 русский-рок；sort：top（默认）或 new；cursor（可选）	每页最多返回 20 个发行作品，每项为 {type, name, artist, slug}，并附有用于获取下一页的 nextCursor。省略 tag 可浏览 Bandcamp 上未经筛选的列表。自由格式的标签会被规范化为 slug 格式（Drum & Bass → drum-bass）。游标只能与其来源标签和排序方式一起使用。

每个 slug 都是从先前结果中复制的 Bandcamp 标识符（<subdomain>/album/<item>、<subdomain>/track/<item>，或艺人或厂牌的纯子域名），而不是显示名称。工具不接受 URL：Bandcamp URL https://<subdomain>.bandcamp.com/album/<item> 会转换为 slug <subdomain>/album/<item>，工具说明会告知模型这一点。slug 为 null 的结果无法查询（见下文的自定义域名）。

已知限制

• 由单个维护者尽力维护的项目，不提供 SLA。 每日冒烟测试仅用于监控，不构成支持保证。
• 提示词注入。 名称、标题、简介、描述和标签由 Bandcamp 用户编写，任何人都可以在 Bandcamp 上发布内容。此服务会解码实体、剥除标记语言以及控制字符和不可见字符，并限制内容长度；每个工具的描述也都会告诉模型将这些内容视为数据，绝不可视为指令。这可以降低精心编写的简介操控助手的风险，但无法彻底消除风险。
• 固定版本和全局安装不会自动修复。 Bandcamp 更改内容并发布修复后，只有未固定版本的 npx 配置会自动获得更新。固定到 @x.y.z 的副本或通过 npm install -g 安装的版本仍会出错，且错误信息不会告诉你已有修复。如果工具报告 Bandcamp 的格式已更改，请查看问题和变更日志，然后更新。
• 自定义域名。 为防止请求被引导至其他服务（SSRF），此服务只会获取 bandcamp.com 和 *.bandcamp.com 主机。对于 Bandcamp 列在自有域名下的发行作品、艺人或厂牌（例如在搜索“carpenter”时出现的 ilistentojohn.com），返回结果中的 slug: null，因此无法根据该结果查询；如果某位艺人的子域名重定向到其自有域名，则会报告未找到，并说明原因。
• 艺人和厂牌没有标签。 它们的页面不包含标签，因此 bandcamp_get_artist 不会返回任何标签；bandcamp_get_album 会返回发行作品的标签。
• 专辑的 label 可能是托管账号名称。 如果页面未注明唱片厂牌，该字段会回退为发布该发行作品的 Bandcamp 账号。对于厂牌自己的页面，这样处理是正确的；如果账号名与署名艺人相同，此服务会忽略该账号。但对于由多个艺人署名、且自行发布的发行作品，如果账号名称与艺人无关（例如乐队、游戏工作室或集体），则会将该账号报告为厂牌。
• bandcamp_get_artist 中的长目录最多截取 100 个发行作品。
• 取消请求不会停止请求执行。 客户端取消的工具调用仍会在后台完成其 Bandcamp 请求（受超时限制）；v1 不会传递取消信号。
• 不提供“推荐”排序。 Bandcamp 仅为已登录的粉丝账号个性化提供该排序；此项目刻意不使用凭据，因此 bandcamp_browse_tag 提供 top 和 new。
• 不在范围内： 登录、你的收藏或愿望清单、购买、销售数据以及远程（HTTP/SSE）传输。此服务仅在本地通过 stdio 运行。

原则

此服务承诺提供什么、拒绝做什么——匿名且只读、使用 slug 而非 URL、不提供任何可能包含流媒体或下载链接的字段，以及 Bandcamp 更改时如实报错——均已记录在 PRINCIPLES.md 中，并附有用于落实各项原则的代码和测试。

贡献

请参阅 CONTRIBUTING.md。

许可证

MIT；请参阅 LICENSE。