sonovault

sonovault-mcp

适用于 SonoVault 音乐元数据 API 的 MCP 服务。让 Claude、Cursor 和任何 MCP 客户端都能搜索 9,300 多万首曲目、艺人、厂牌和发行作品，并获取每条结果的完整元数据：流派、BPM、调性、厂牌、发行日期、艺人署名、ISRC 和 ISWC 代码，以及跨平台 ID（Spotify、Apple Music、Tidal、Beatport、Discogs、MusicBrainz、YouTube）。

你可以向助手提出这类问题：

• “mau5trap 今年发行了哪些作品？”
• “查找 Daft Punk 的 Veridis Quo，并告诉我它的流派、厂牌和 ISRC”
• “One More Time 的调性和 BPM 是多少？Discovery 中有哪些曲目适合与它混音？”
• “显示 Discovery 的曲目列表及 ISRC”
• “ISRC GBDUW0000053 对应的 Spotify 和 Beatport ID 是什么？”
• “将这份播放日志解析为 ISRC 和厂牌”（最多粘贴 100 行）
• “列出 ISWC T-071.020.439-9 的所有录音”

设置

你需要一个 SonoVault API 密钥。免费套餐每月可发送 1,000 次请求，无需信用卡：获取密钥。

Claude Desktop

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "sonovault": {
      "command": "npx",
      "args": ["-y", "sonovault-mcp"],
      "env": { "SONOVAULT_API_KEY": "svk_live_..." }
    }
  }
}

Claude Code

claude mcp add sonovault -e SONOVAULT_API_KEY=svk_live_... -- npx -y sonovault-mcp

Cursor

添加到 ~/.cursor/mcp.json（或项目中的 .cursor/mcp.json）：

{
  "mcpServers": {
    "sonovault": {
      "command": "npx",
      "args": ["-y", "sonovault-mcp"],
      "env": { "SONOVAULT_API_KEY": "svk_live_..." }
    }
  }
}

VS Code（GitHub Copilot）

添加到 .vscode/mcp.json：

{
  "servers": {
    "sonovault": {
      "command": "npx",
      "args": ["-y", "sonovault-mcp"],
      "env": { "SONOVAULT_API_KEY": "svk_live_..." }
    }
  }
}

Windsurf

将与 Claude Desktop 相同的 mcpServers 块添加到 ~/.codeium/windsurf/mcp_config.json。

其他 MCP 客户端

任何通过 stdio 使用 MCP 协议的客户端都能正常工作。命令：设置 SONOVAULT_API_KEY 环境变量后运行 npx -y sonovault-mcp。

工具

工具	功能
search_tracks	按艺人和曲名进行模糊搜索。返回 ISRC、流派、BPM、调性、厂牌和发行日期。
lookup_isrc	按 ISRC 精确查找录音，并返回 BPM 和调性。
get_track	按 SonoVault ID 获取曲目，并返回 BPM 和调性。
get_work_codes	从录音追溯到作品：获取录音对应的 ISWC。
get_recordings_of_work	从作品查找录音：获取某个 ISWC 对应的所有录音。
get_platform_links	根据任意 ID 或 ISRC，获取一首曲目在全部 7 个平台上的 ID 和深层链接。
resolve_tracks	批量解析最多 100 个曲名、ISRC 或平台 ID。
search_artists, get_artist_releases	搜索艺人及其唱片目录，并提供 Wikidata 和 MusicBrainz 标识符。
search_labels, get_label_releases	搜索厂牌及其目录，可按单个发行日期或日期范围筛选。
search_releases, get_release	搜索发行作品，并按播放顺序显示曲目列表，其中包含 ISRC、BPM、调性、碟片号和曲目号，以及 MusicBrainz 发行作品和发行组 ID。get_release 还会列出发行作品背后的实际版本，每个版本都有自己的厂牌和目录编号；传入 edition ID 即可显示该版本的编号。
list_genres	获取标准流派层级。
browse_tracks	按厂牌、艺人、流派或年份浏览曲目（付费套餐）。

所有工具均为只读。大多数工具在免费套餐中可用；browse_tracks 需要付费套餐。

工作流示例

丰富电台播放日志，用于版税报告

粘贴只包含艺人和曲名的播放日志，并询问：“将这些内容解析为 ISRC、专辑和厂牌，并以表格形式列出，方便我映射到 SoundExchange Report of Use。”助手每 100 行调用一次 resolve_tracks，并返回集体管理组织用于匹配的标识符。用于 PPL、Sena、GVL 和 Re:Sound 报告时也同样适用。

整理 DJ 曲库

“这是从我的 rekordbox 导出的 50 首曲目。找出每首曲目的标准版本，标记共享 ISRC 的重复曲目，并为每首曲目添加流派、BPM 和调性标签。”助手会结合使用 resolve_tracks 以及每条结果中的流派、速度和调性字段。

将录音关联到作品

“我从发行商那里拿到了 ISRC。这些录音对应哪些音乐作品？每部作品还有哪些其他录音版本？”助手会依次调用 get_work_codes 和 get_recordings_of_work。适用于版权管理及翻唱／版本研究。

检查跨平台可用情况

“这首 Beatport 独占曲目现在能在 Spotify 上听了吗？Beatport ID 6014288。”调用一次 get_platform_links 即可得到答案，并提供各平台的深度链接。

研究唱片公司

“按子流派汇总 Anjunabeats 过去六个月发行的作品。”助手会分页调用 get_label_releases，并从曲目列表中提取流派。

常见问题

有免费套餐吗？

有。免费的 SonoVault 密钥每月包含 1,000 次请求，无需信用卡。除 browse_tracks 外，所有工具都可使用。

每首曲目包含哪些元数据？

标题、艺人署名（含主要艺人／混音者标记）、ISRC、时长、BPM、调性、流派和子流派，以及每个发行版本的专辑标题、唱片公司和发行日期。ISWC 作品代码由专用的作品代码工具提供。

是否会返回 BPM 或调性？

会。每首曲目都包含 bpm（完整速度，最多保留 2 位小数，因此 174 而非 87）及三种记法的调性：

• key_alphanumeric：1 到 12，加上表示小调的 A 或表示大调的 B，例如 10B。相邻数字以及数字相同但字母不同的调性，在和声上相融。
• key_musical：标准记法，例如 D、Am、F#m、Ebm。
• key_open：Open Key 记法，使用小写字母，例如 3d、1m。

keys 会列出该曲目的所有调性，每个来源对应一条记录。调性来自 OpenKeyScan，BPM 则来自 Lexicon DJ 节拍检测器（深受 10 万多名 DJ 信赖）；两者均由 SonoVault 根据音频分析得出。Daft Punk 的 One More Time 会返回 123 BPM，以及 10B / D / 3d。尚未分析的曲目，这些值均为 null，且 keys 为空。不会提供能量或舞蹈性等其他音频特征。

数据来自哪里？

数据汇总并去重自 MusicBrainz、Discogs、Spotify、Apple Music、Tidal 和 Beatport，ISWC 链接来自 The MLC。详情见：sonovault.now/data-sources。

这与 Spotify API 集成有何不同？

单平台 API 只返回各自平台的 ID。SonoVault 以 ISRC 为依据，将一条录音关联到所有七个受支持平台上的对应 ID，并补充平台 API 不提供的标识符（ISRC、ISWC）。对比：sonovault.now/compare/spotify-api。

我的 API 密钥除了 SonoVault 之外还会发送到其他地方吗？

不会。该服务通过 stdio 在本地运行，只会将密钥作为请求标头发送到 api.sonovault.now。代码简短且可供审查：src/server.ts。

Agent Skill

不使用 MCP？skill/SKILL.md 是一项 Agent Skill，可教会任意 Agent 通过 HTTP 直接调用 SonoVault API：搜索规则、ISRC／ISWC 操作指南、批量解析和错误处理。

相关链接

• SonoVault API 文档
• sonovault-js 和 sonovault-python，即客户端 SDK（此服务基于 sonovault-js 构建）

许可证

MIT