开发者与 MCP 接入

您的智能体可以通过 MCP 或 REST 接口检索 Kindle Music 正版商用曲库、查找相似曲目，并生成可试听的选曲结果页。

接入地址

MCP（推荐）：OAuth 登录授权，无需 API key，客户端首次连接时会引导您登录 Kindle Music 完成授权。https://share.kindlemusic.cn/mcp/oauth
MCP（API key 方式）：请求头带 Authorization: Bearer kmak_…；不带 key 只能使用开放工具。https://share.kindlemusic.cn/mcp
OpenAPI（REST，每个工具对应一条 POST 接口）：https://share.kindlemusic.cn/agent/v1/openapi.json
工具清单 tools.json：https://share.kindlemusic.cn/agent/v1/tools.json
MCP server card：https://www.kindlemusic.cn/.well-known/mcp/server-card.json

API key 可在账户的「API Keys」页自助创建：免费，每人最多 5 把，每把每日有 AI 检索额度。前往创建 API key →

工具一览

km_vocabulary — 列出曲库全部可用的筛选值（流派、情绪、乐器、速度、适用场景、厂牌），使用筛选条件前先查。
km_normalize_brief — 把结构化选曲需求（情绪、流派、场景、乐器、BPM 区间、成片时长等）归一化成可直接执行的检索条件。
km_search — 按关键词、描述句、筛选条件、BPM 与时长检索曲目或专辑，返回曲目信息与可在网站上复现本次检索的链接。
km_resolve — 把下载文件名、UPM 链接、本站链接或 PUC-045 这类编号定位到专辑或曲目。
km_track_versions — 列出同一首曲子的全部剪辑版本（完整版、60 秒、30 秒、15 秒等）。
km_similar_by_track — 以曲库里的一首曲目为参照，查找听感相似的曲目。
km_request_upload — 申请一次性的参考音频上传地址（30 分钟内有效，用一次即作废）。
km_similar_by_audio — 用上传的参考音频查找听感相似的曲库曲目。
km_create_result_set — 把挑好的曲目发布成可分享的选曲结果页，打开即可试听、对比。
km_get_result_set — 按编号读回一份已发布的选曲结果页（含分段、曲目与在架状态）。

在您的客户端里接入

在终端运行下面的命令，然后在 Claude Code 里输入 /mcp，选择 kindlemusic → Authenticate，浏览器会打开 Kindle Music 登录授权页：

claude mcp add --transport http --scope user kindlemusic https://share.kindlemusic.cn/mcp/oauth

或使用 API key：

claude mcp add --transport http --scope user kindlemusic https://share.kindlemusic.cn/mcp --header "Authorization: Bearer kmak_你的key"

请把 kmak_你的key 替换为您的 API key。先去获取 API key →

一键添加到 Cursor

或手动写入 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "kindlemusic": {
      "url": "https://share.kindlemusic.cn/mcp/oauth"
    }
  }
}

一键添加到 VS Code

或手动写入项目的 .vscode/mcp.json：

{
  "servers": {
    "kindlemusic": {
      "type": "http",
      "url": "https://share.kindlemusic.cn/mcp/oauth"
    }
  }
}

Claude（网页版与桌面 App）：设置 → 连接器 → 添加自定义连接器，名称填 Kindle Music、URL 填下面的地址（OAuth Client ID / Secret 留空），保存后点「连接」并登录 Kindle Music 授权，再在对话输入框的工具菜单里启用。Team / Enterprise 账号需由组织管理员添加。ChatGPT：开启开发者模式后在设置里添加连接器，URL 同样填下面的地址。

https://share.kindlemusic.cn/mcp/oauth

在 WorkBuddy 的连接器市场搜索「Kindle Music」（OAuth 版审核中），或手动添加如下配置：

{
  "mcpServers": {
    "kindlemusic": {
      "type": "streamableHttp",
      "url": "https://share.kindlemusic.cn/mcp/oauth"
    }
  }
}

其他支持 MCP 的客户端使用 API key 时的通用配置：

{
  "mcpServers": {
    "kindlemusic": {
      "type": "streamableHttp",
      "url": "https://share.kindlemusic.cn/mcp",
      "headers": {
        "Authorization": "Bearer kmak_你的key"
      }
    }
  }
}

请把 kmak_你的key 替换为您的 API key。先去获取 API key →

REST 接口的完整说明见 OpenAPI：

https://share.kindlemusic.cn/agent/v1/openapi.json

调用示例（开放工具可省略 Authorization 请求头）：

curl -X POST https://share.kindlemusic.cn/agent/v1/km_search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer kmak_你的key" \
  -d '{"keyword":"uplifting corporate piano","pageSize":5}'

请把 kmak_你的key 替换为您的 API key。先去获取 API key →

如何写好检索描述

检索效果几乎完全取决于描述里有多少「关于音乐」的信息。以下要点写给智能体与开发者，可直接放进您的提示词。

五段描述公式

用在哪儿 + 什么情绪、怎么变化 + 什么乐器或风格 + 多快、怎么推进 + 不要什么。场景具体到画面位置（如「汽车广告结尾品牌露出」）；情绪用两三个词定位，并说明强度与走向；点名一个主奏乐器胜过十个形容词。五段不必写全，「场景 + 任意一两段」就明显好于单个形容词。

示例：汽车广告结尾品牌露出，高级、自信、有向上的力量感，弦乐和钢琴为主、带一点现代电子质感，中速、逐渐推进到最后一个高点，纯器乐，不要人声。

剧情写一句，音乐写三句：「逆袭」「对峙」「回忆」这类剧情词在曲库标签里很少出现，先翻译成情绪、乐器、速度这类音乐描述再检索。

按需求选检索模式

keywords：一两个明确的词。多个词之间是「或」、按命中词数排序，所以要加不同维度的词（用途 + 情绪 + 乐器），别堆近义词；英文双引号是短语匹配。中文需带 expand（fast 快而宽，deep 更准更窄、最长约 1 分钟），否则只接受英文。

ai：一句完整的自然语言描述（可以是中文），整句理解后再检索；看排在前面的结果，而不是总数。

有参考曲时：曲库内的曲目用 km_similar_by_track；外部音频先 km_request_upload 上传，再用 km_similar_by_audio。

找具体的曲子或专辑：track 用英文原曲名，album 用专辑名或编号；手里是文件名、链接或编号时，先用 km_resolve 定位，不要当关键词搜。

否定怎么写

ai 模式可以把「不要人声」「去掉鼓」直接写进句子，一次最多 4 项；「不要太悲伤」只会让悲伤的曲子往后排，不会全部去掉。keywords 模式下英文的 no / without 不会被识别，后面的词反而会被当作要找的内容。客户的硬性排除，任何模式都请用 exclude 筛选兜底（取值先用 km_vocabulary 查）。

少条件起步，再逐步放宽

先用三四个最重要的条件出结果，看过再加；一上来就写十个限制条件，很容易一首都搜不到。结果太少时，按「速度 → 时长 → 情绪 → 风格 → 乐器」的顺序逐类放宽。按 BPM 收窄时注意半速记法（60 与 120 常是同一个脉冲），把半速区间也检索一遍。

音频使用说明

接口返回的 track_url 等地址是版权制作音乐的试听流，仅供试听与临时分析，不得转存、分发或放进交付物。需要音频文件时，请在选曲结果页试听后登录下载，或提交授权申请。