musicbrainz-mcp-server

---

概览

来自 MusicBrainz 和 Cover Art Archive 的开放音乐元数据：艺术家、发行作品、录音、作品和厂牌。按名称搜索，使用 MBID、ISRC、ISWC 或条形码查询，翻阅完整唱片目录，并获取封面图。

工具

工具	描述
musicbrainz_search_entities	对一种实体类型执行 Lucene 搜索，返回按相关性排序的 MBID 及相关性评分
musicbrainz_get_artist	艺术家资料：类型、存续时间、唱片目录、关联关系、外部链接
musicbrainz_get_release_group	发行组（跨不同版本的专辑）：类型、首次发行日期、版本、封面图可用情况
musicbrainz_get_release	一个版本：曲目列表、厂牌和目录编号、条形码、包装
musicbrainz_get_recording	录音（一次表演）：时长、ISRC、收录该录音的发行作品、表演者和制作人员署名
musicbrainz_get_work	作品（一个创作）：类型、ISWC、作者、乐章、编曲和录音
musicbrainz_get_label	厂牌：类型、存续时间、厂牌代码、外部链接
musicbrainz_lookup_identifier	将 ISRC、ISWC 或条形码解析为录音、作品或发行作品
musicbrainz_browse_entities	翻阅与父级 MBID 关联的所有实体
musicbrainz_get_cover_art	获取发行作品或发行组的 Cover Art Archive 图片

资源

资源	描述
musicbrainz://{entity_type}/{mbid}	单个实体的原始 MusicBrainz JSON，其中包含对应 get_* 工具返回的关联数据

每个实体也都可以通过 get_* 工具访问，因此仅支持工具的客户端不会缺少任何功能。此资源没有列表；请使用 musicbrainz_search_entities 查找 MBID。

功能参考

musicbrainz_search_entities _工具

• 每次调用指定一个 entityType（artist、release-group、release、recording、work、label），并提供支持字段限定的 Lucene query（artist:radiohead AND country:GB）；limit 必须为正整数（默认值为 25，超过 100 的值会被限制为 100，并附带提示），offset 用于分页
• 返回生效的 offset 和上游 totalCount。续页时使用 offset + 返回的行数，包括不足一页的情况。在正数总数范围内或之后返回空页时，会报告已无更多结果；如果在总数之前意外返回空页，则会报告差异，但不会建议使用不前进的 offset
• 每条结果都按 MusicBrainz 顺序包含 mbid、name 和原始的 0–100 score，以及特定类型的字段，例如 artistCredit、isrcs、iswcs 和 length。Release 行使用 status（Official、Bootleg 等）；artist、release-group、work 和 label 子类型使用 type。仅含空白字符的查询会以 blank_query 失败

---

musicbrainz_get_artist _工具

• mbid，以及用于移除较重子资源的 inc_release_groups 和 inc_relationships（两者默认均为 true）
• 类型、性别、国家、地区、lifeSpan、别名和标签，以及 releaseGroups（一页）、relationships（乐队成员身份、合作关系）和 externalLinks（Wikidata、Discogs、官方网站）

---

musicbrainz_get_release_group _工具

• 仅需 mbid；返回 primaryType、secondaryTypes、firstReleaseDate、包含 artistCreditString 的 artistCredit、标签，以及一页 releases（版本）
• coverArt（exists、count、front、back）来自实时 Cover Art Archive 检查；检查失败时会附带提示并省略该字段，绝不会报告为“无封面”

---

musicbrainz_get_release _工具

• mbid、media_offset（默认值为 0）和 media_limit（默认值为 20，无上限）；返回有序的 media，其中包含每种媒介的完整曲目（position、title、以 m:ss 表示的 length、recordingId）、labelInfo（厂牌和 catalogNumber）、barcode、status、date、country、packaging、language/script 和 releaseGroupId
• mediaTotal 和 trackTotal 统计所有规范化的媒介和曲目出现次数；保留上游每种媒介的 trackCount。mediaOffset 用于标识当前窗口。还有更多媒介时，truncated、shown、cap 和提示会给出下一个 media_offset；末尾空页会报告已无更多结果。Release 资源保留完整的原始曲目列表
• coverArt 是 release 记录提供的可用性占位字段；如需图片 URL，请调用 musicbrainz_get_cover_art

---

musicbrainz_get_recording _工具

• mbid，以及用于获取表演者、制作人和录音工程师署名、指向作品的链接和外部链接的 inc_relationships（默认值为 true）
• 返回 length、isrcs、artistCredit、firstReleaseDate、一页上游 releases（最多 25 条）、relationships 和 externalLinks
• releaseAppearanceSummary 报告 shown、cap: 25 和 completeness：存在且未满页时为 complete；没有精确计数的满页或缺失页面时为 unknown；如果精确的上游计数超过返回页数，则证明结果已被截断。计数未知时会省略 totalCount；不会额外请求计数。请使用 musicbrainz_browse_entities（target_type=release、link.recording=<mbid>、offset=0）枚举这些出现记录，因为内嵌顺序可能与浏览顺序不同

---

musicbrainz_get_work _工具

• 需要 mbid，以及用于获取创作者、作曲者和作词者署名、乐章与编曲、演绎该作品的录音和外部链接的 inc_relationships（默认值为 true）
• 返回 type、languages、iswcs、别名和标签。最多保留前 25 条录音关系（其他关系和链接均会保留）；totalCount 提供完整数量，如果有条目被截断，则会显示 truncated、shown 和 cap
• 若要列出作品的所有录音，请按 work 浏览 recording，然后调用 musicbrainz_get_recording 获取关系属性和日期
• 对于 targetType: "work" 的 relationships 条目，请在另一次 musicbrainz_get_work 调用中使用其 targetId。direction 用于区分父级／子级链接；可选的 orderingKey 会保留上游序列键（包括零），而 targetDisambiguation 用于区分编曲。关系会保留上游数组顺序，但该顺序不一定与乐章顺序一致

---

musicbrainz_get_label _工具

• 仅需 mbid；返回类型、国家／地区、区域、lifeSpan、labelCode（不含前缀的 LC 编号）、别名、标签和 externalLinks
• 不会嵌入发行信息；请使用 musicbrainz_browse_entities 列出发行信息（target_type=release、link.label）

---

musicbrainz_lookup_identifier _工具

• id_type 为 isrc 时返回录音，为 iswc 时返回作品，为 barcode 时返回发行；条形码为 UPC/EAN 数字，并返回最多 25 个按排名排列的匹配项，每项都包含一个 score
• ISRC 可使用紧凑格式 GBAYE9701274 或印刷格式 GB-AYE-97-01274；不区分大小写，并忽略首尾空格。ISWC 可使用 T-010.140.236-1 或 T0101402361，可带可选的分组标点；不区分大小写，并忽略空格。结果会回显规范的紧凑格式 ISRC 或 T-DDD.DDD.DDD-C 格式的 ISWC；格式错误的代码会在发起请求前报错
• result.kind（recordings | works | releases）标明返回的结果类型；失败时返回 invalid_identifier 或 identifier_not_found

---

musicbrainz_browse_entities _工具

• 需要 target_type，以及 link 中恰好一个父级 MBID；releaseGroup／release_group 是 release-group 的别名。正整数 limit 默认为 25；超过 100 的值会被限制为 100，并显示提示。设置 MUSICBRAINZ_CLAMP_OVERSIZED_LIMITS=off，可在搜索和浏览时强制执行 100 的上限
• 报告上游 totalCount；如果仍有更多结果，则会设置 truncated，且非空页面会根据实际返回的行数提供下一个 offset。空页面会区分没有关联实体、结果已取完，以及在达到总数前出现意外空页面的情况。上限和分页指导会共用一条提示。发行行使用 status；其他实体使用 type
• 缺少、多出或格式错误的链接会导致 invalid_link；未知父级会导致 entity_not_found。若要获取某一版本的有序曲目，请使用 musicbrainz_get_release

目标	接受的父级键
artist	area、recording、release、release-group、work
label	area、release
release-group	artist、release
release	area、artist、label、recording、release-group
recording	artist、release、work
work	artist

---

musicbrainz_get_cover_art _工具

• mbid 和 entity_type：release（默认值）或 release-group，后者会解析为 representativeRelease；limit 默认值为 25，超过 100 时会截断至 100；offset 默认值为 0。这些分页窗口会在缓存档案索引后应用，且独立于搜索/浏览截断设置
• images 按档案顺序保留，包含 front/back、types、imageUrl 以及 250/500/1200px 缩略图。totalCount 为准确总数，offset 标识当前窗口；即使在末尾空页面，hasArt 也反映整个档案是否有图片。单条提示会汇总截断、继续获取、无更多结果或无图片等说明；有更多图片时会显示 truncated、shown 和 cap
• 未知 MBID 会以 entity_not_found 错误失败；如果 MusicBrainz 无法确认 MBID 是否存在，则会返回空集合，并附带相应提示

---

musicbrainz://{entity_type}/{mbid} _资源

• entity_type 可以是 artist、release-group、release、recording、work 或 label；以 application/json 格式返回原始 MusicBrainz 记录
• 获取与对应 get_* 工具相同的默认关联数据；失败时返回 invalid_mbid 或 entity_not_found
• Work JSON 包含原始的 work-to-work 关系，并保留前 25 条录音关系；recordingRelationshipSummary 提供准确的录音数量，并说明是否有关系被截断
• Recording JSON 携带与录音工具相同的 releaseAppearanceSummary，且不会更改缓存的原始数据。Release JSON 会保留所有介质和曲目；工具的介质分页窗口不适用于资源

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可替换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），以及支持可选 OpenTelemetry 跟踪的结构化日志。

MusicBrainz 专属功能：

• 面向 MusicBrainz Web Service v2 和 Cover Art Archive 的免密客户端。每个请求都会携带 MusicBrainz 要求的说明性 User-Agent：musicbrainz-mcp-server/<version> ( <contact> )，其中联系人为 MUSICBRAINZ_CONTACT
• 实体通过 MBID（带连字符的 UUID）标识；大写字母和首尾空格会被规范化。格式错误或全零 ID 会以 invalid_mbid 失败（浏览时为 invalid_link）；格式正确但未知的 ID 会以 entity_not_found 失败
• 同一实例的所有客户端对 MusicBrainz 的调用频率限制为约每秒 1 次，因此长时间的浏览任务需要等待一段时间
• 一次请求即可整合唱片目录、关系、曲目列表和外部链接；响应默认缓存 24 小时，并会通过退避重试暂时性上游错误

适合 Agent 使用的输出：

• 艺术家发行组、发行组版本和录音发行记录会内嵌一页（25 条）；浏览操作会枚举完整集合。录音发行记录会说明数据是否完整，无需额外请求数量。Work 的录音关系最多为 25 条，并会报告准确数量；标签不会内嵌发行记录
• 搜索结果会回显实际使用的查询；搜索和浏览会报告准确的上游总数。总数缺失或无效时，会以格式错误的上游响应处理，而不会臆造数量
• 区分式输出：musicbrainz_lookup_identifier 返回带 kind 标签的联合类型，调用方可根据数据分支处理，无需解析字符串
• 使用上游原始相关性 score，而非推导出的置信度；上游缺失的字段会保持缺失，不会臆造

开始使用

公共托管实例

现已提供公共实例：https://musicbrainz.caseyjhand.com/mcp，无需安装。通过 Streamable HTTP 将任意 MCP 客户端指向该实例：

{
  "mcpServers": {
    "musicbrainz-mcp-server": {
      "type": "streamable-http",
      "url": "https://musicbrainz.caseyjhand.com/mcp"
    }
  }
}

自托管 / 本地

将以下内容添加到 MCP 客户端配置文件中。

{
  "mcpServers": {
    "musicbrainz-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/musicbrainz-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "MUSICBRAINZ_CONTACT": "[email protected]"
      }
    }
  }
}

或者使用 npx（无需 Bun）：

{
  "mcpServers": {
    "musicbrainz-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/musicbrainz-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "MUSICBRAINZ_CONTACT": "[email protected]"
      }
    }
  }
}

或者使用 Docker：

{
  "mcpServers": {
    "musicbrainz-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-e", "[email protected]",
        "ghcr.io/cyanheads/musicbrainz-mcp-server:latest"
      ]
    }
  }
}

对于 Streamable HTTP，设置传输方式并启动服务：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 [email protected] bun run start:http
# Server listens at http://localhost:3010/mcp

前置条件

• Bun v1.4.0 或更高版本（或 Node.js v24+）。
• 无需 API 密钥或账户。服务附带默认联系人，但在任何共享或托管部署中，请将 MUSICBRAINZ_CONTACT 设置为你自己的电子邮件地址或 URL。

安装

1. 克隆仓库：

git clone https://github.com/cyanheads/musicbrainz-mcp-server.git

2. 进入目录：

cd musicbrainz-mcp-server

3. 安装依赖项：

bun install

4. 配置环境：

cp .env.example .env
# edit .env and set MUSICBRAINZ_CONTACT (optional but recommended)

配置

变量	说明	默认值
MUSICBRAINZ_CONTACT	在 User-Agent 中发送的电子邮件地址或 URL；在共享或托管实例中，请设置为你自己的值。	仓库 URL
MUSICBRAINZ_BASE_URL	MusicBrainz Web Service v2 基础 URL（例如，私有镜像）。	https://musicbrainz.org/ws/2
MUSICBRAINZ_RATE_LIMIT_RPS	客户端每秒请求数上限（0.1–50）。	1
MUSICBRAINZ_CACHE_TTL	响应缓存 TTL，单位为秒；0 表示禁用缓存。	86400
MUSICBRAINZ_TIMEOUT_MS	每个请求的 HTTP 超时时间，单位为毫秒。	30000
MUSICBRAINZ_MAX_RETRIES	上游发生暂时性故障时的重试次数。	3
MUSICBRAINZ_CLAMP_OVERSIZED_LIMITS	将超过 100 的搜索/浏览限制截断为 100，并发出提示；设为 off 可恢复最大值为 100 的架构验证。严格布尔值（true/false、on/off、1/0、yes/no）。	true
COVER_ART_BASE_URL	Cover Art Archive 基础 URL。	https://coverartarchive.org
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务端口。	3010
MCP_AUTH_MODE	身份验证方式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（debug、info、warning、error 等）。	info
OTEL_ENABLED	启用 OpenTelemetry。	false

完整的可选覆盖项列表请参阅 .env.example。

运行服务

本地开发

• 构建并运行：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• 运行检查和测试：

  bun run devcheck   # Lint, format, typecheck, security, packaging
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against the linter rules
  

Docker

docker build -t musicbrainz-mcp-server .
docker run --rm -e [email protected] -p 3010:3010 musicbrainz-mcp-server

Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/musicbrainz-mcp-server。默认会安装 OpenTelemetry 对等依赖项；构建时使用 --build-arg OTEL_ENABLED=false 可省略这些依赖项。

项目结构

目录	用途
src/index.ts	createApp() 入口点——注册工具和资源，并初始化两项服务。
src/config	使用 Zod 解析并验证服务专用环境变量。
src/services/musicbrainz	MusicBrainz WS/2 客户端——User-Agent、速率限制器、响应缓存、重试和领域类型。
src/services/cover-art	Cover Art Archive 客户端——将 404 映射为空图像集，并跟随发行组重定向。
src/mcp-server/tools	工具定义（*.tool.ts）。涵盖搜索、查询、浏览和封面艺术的十个只读工具。
src/mcp-server/resources	资源定义。musicbrainz://{entity_type}/{mbid} 实体镜像。
tests/	与 src/ 结构对应的单元测试和集成测试。

开发指南

开发指南和架构规则请参阅 CLAUDE.md/AGENTS.md。简要说明：

• 处理程序抛出异常，由框架捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录请求级日志，使用 ctx.state 存储租户级数据
• 通过 src/mcp-server/*/definitions/index.ts 中的 barrel 文件注册新工具和资源
• 所有上游调用都必须通过服务发出，绝不能直接调用 fetch()，以确保应用 User-Agent、速率限制器和缓存
• 包装外部 API 数据：验证原始数据 → 规范化为领域类型 → 返回输出架构；绝不伪造缺失字段

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

Apache-2.0 — 详情请参阅 LICENSE。

MusicBrainz 核心实体数据采用 CC0 许可。服务仅读取这些核心元数据，不会获取注释文本，因为注释文本采用不同的许可证。封面图片来自 Cover Art Archive，这是 MusicBrainz 与 Internet Archive 的联合项目；图片 URL 仅作为链接提供，不会重新托管，每张图片的版权仍归其权利持有人所有。在下游使用中，请注明 MusicBrainz 和 Cover Art Archive。