musicbrainz-mcp

musicbrainz-mcp

面向 MusicBrainz（开放音乐百科全书）的 MCP 服务。它让 Claude 能够实时访问 MusicBrainz 元数据，包括艺术家、发行物、录音、厂牌、作品等，还能访问 Cover Art Archive 图片；此外，（可选）还允许你提交自己的标签、评分和收藏集修改。

由 AI（Claude Code）开发和维护。请自行斟酌使用。

工具

读取（无需凭据）：

工具	功能
musicbrainz_search	使用 Lucene 查询搜索任意实体类型；返回按相关性排序的匹配项和 MBID
musicbrainz_lookup	根据 MBID 查找实体，并通过 inc 子查询获取关联数据
musicbrainz_browse	列出与另一实体关联的所有实体（例如某位艺术家的所有发行物）
musicbrainz_cover_art	获取发行物 / 发行组的 Cover Art Archive 图片 URL
musicbrainz_resolve	将粘贴的 musicbrainz.org URL 转换为对应实体
musicbrainz_healthcheck	验证连接状态，以及是否已配置 OAuth 写入功能

写入（OAuth，发送前需确认）：

工具	功能
musicbrainz_submit_tags	将用户标签应用到你账户中的实体
musicbrainz_submit_rating	设置你对某个实体的 0–100 分评分
musicbrainz_modify_collection	在你的收藏集中添加或移除实体

每次写入操作都会先要求你确认，然后才会发起网络请求——请参阅确认。

除 musicbrainz_cover_art 外，上述所有读取工具都接受 view 参数。默认值为 compact，会移除图片和头像 URL——这是一条只会减少字段的规则，因此不会 丢弃未知字段；view: "full" 则原样返回 MusicBrainz 的响应内容。 musicbrainz_cover_art 刻意不接受该参数：图片 URL 就是 它的结果，移除这些 URL 不会缩小响应内容，只会让响应变空。

安装

这是一个 Node MCP 服务（stdio）。将 MCP 宿主指向它：

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

读取功能立即可用。MusicBrainz 要求客户端每秒最多发送一个请求——服务会自行限流以遵守此限制，因此大型浏览操作会自动控制请求节奏。

启用写入工具（可选）

1. 在 musicbrainz.org/account/applications 注册应用（重定向 URI 为 urn:ietf:wg:oauth:2.0:oob）。
2. 使用 tag、rating 和 collection 权限范围完成 OAuth 流程，以获取刷新令牌。
3. 通过 MCP 宿主的环境变量（或本地 .env）提供以下内容：

MUSICBRAINZ_OAUTH_CLIENT_ID=...
MUSICBRAINZ_OAUTH_CLIENT_SECRET=...
MUSICBRAINZ_OAUTH_REFRESH_TOKEN=...

确认

每次写入都会先征求你的确认。能够显示确认提示的客户端（Claude Code）会显示提示，其中包含实体、标签／评分／合集变更。不支持显示确认提示的客户端（claude.ai、Claude Desktop）则使用两步流程：首次调用不会提交任何内容，而是返回 confirmation-required 预览——标签和评分对应的确切 XML，合集对应的方法和路径——以及 confirmToken；只有使用该令牌重复相同调用才会提交。令牌只能使用一次，且两次调用之间任何参数发生变化都会使令牌失效。

变量	默认值
MCP_CONFIRM_MODE	ask-user	在无法显示确认提示的客户端（claude.ai、Claude Desktop）上，写入操作的处理方式。ask-user：分两步进行——首次调用不执行任何操作，并返回预览和令牌；模型必须先在聊天中获得你的批准，才能使用该令牌再次调用。auto：同样分两步进行，但模型查看预览后可以自行使用令牌。refuse：在此类客户端上拒绝写入。能够显示提示的客户端（Claude Code）始终会显示实际提示，除非 MCP_CONFIRM_ELICITATION=off。无法识别的值会按 refuse 处理。
MCP_CONFIRM_ELICITATION	on	off 表示绝不显示确认提示，因此所有客户端都会遵循 MCP_CONFIRM_MODE 的行为。如果某个客户端声称能够显示提示，却始终不显示（写入操作会一直挂起——opencode 2.0.x），请设置此项。其他任何值都会按 on 处理，并在 stderr 上显示警告。
MCP_CONFIRM_TTL_SECONDS	600	令牌的有效时长。
MCP_CONFIRM_SECRET	每个进程随机生成	签名密钥；仅当令牌必须在服务重启后仍然有效时才设置。

开发

npm install
npm run build
npm test

架构请参阅 CLAUDE.md，固定的 API 结构请参阅 docs/MUSICBRAINZ-API.md。

许可证

MIT。MusicBrainz 数据采用 CC0 / CC BY-NC-SA 许可。