audial-mcp

audial-mcp

由 Audial 提供支持 — 可在任意 MCP 客户端中运行 Audial 托管的音频工具：分离音轨、分析和分段音频、母带处理、构建采样包、将 音频转换为 MIDI、生成音乐、将单次采样转换为可编辑的 Audial Synth 预设，以及用参考人声演唱 歌词。有关每个工具调用的详细信息，请参阅 API 参考。

mcp-name: io.github.AudialAI/audial-mcp

安装

你需要一个 Audial 账户（https://audialmusic.ai?utm_source=github&utm_medium=readme&utm_campaign=mcp）和 uv。无需复制 API 密钥： 首次运行工具时，浏览器会打开登录页面。授权后，工具便会继续运行。

Claude Code

claude mcp add audial -e AUDIAL_RESULTS_DIR=~/Audial -- uvx audial-mcp

Claude Desktop / Cursor / 任意使用 JSON 配置的客户端

{
  "mcpServers": {
    "audial": {
      "command": "uvx",
      "args": ["audial-mcp"],
      "env": {
        "AUDIAL_RESULTS_DIR": "~/Audial"
      }
    }
  }
}

登录

登录信息会保存在你的电脑上（~/.audial/credentials.json，只有你能读取），并与 audial 命令行和 Python SDK 共享，因此在终端中运行 audial login 也会让 MCP 服务登录。如果你在两分钟内没有完成授权，工具会返回 登录链接；完成授权后再试一次。account、sign_in 和 sign_out 工具可显示和更改当前登录账户；你连接的每台电脑都会列在个人资料中的 audialmusic.ai「Apps & API Keys」下，也可在此断开连接。

在无人能够登录的服务器或 CI 环境中，请将 AUDIAL_API_KEY 设置为在该页面创建的密钥。以此方式设置的密钥优先于已保存的登录信息。

工具

工具	功能
stem_split	将曲目分离为人声、鼓、贝斯和其他音轨（可选调整速度／调性）
analyze	分析 BPM、调性和其他特征
segment	乐段和组成部分分析——先分离音轨，再进行分段；一次调用即可完成
master	母带处理，可选择与参考音频匹配
generate_samples	根据曲目生成采样包——先分离音轨，再构建采样包；一次调用即可完成
generate_midi	将音频转换为 MIDI
generate_music	使用 Audial 音乐模型进行文本生成音乐、翻唱、混音、提取和补全
sound2vital	将单次采样转换为可编辑的 Audial Synth（Vital）预设
text2vox	根据歌词和参考人声生成演唱人声与 MIDI
pipeline_status	按 ID 查询工作流：其状态、每个步骤及当前输出
service_status	查看当前有哪些工具的工作进程处于唤醒状态，以及冷启动的费用
list_results	浏览结果文件夹中的历史结果

segment 和 generate_samples 以 Audial 工作流 的形式运行：两者都需要分离后的音轨，因此 API 会先分离音轨，然后在一个任务中运行你请求的步骤。每个步骤开始和完成时都会报告状态（“音轨分离已在 41 秒内完成；采样包生成中”），工作流 ID 会作为结果的 execution_id 返回——如果调用超时，可将其传给 pipeline_status 查询任务状态。

每音符歌词

text2vox 会将歌词与旋律对齐。lyrics_mode="per_note" 模式可实现精确控制：歌词以竖线分隔，每个 MIDI 音符对应一个词元；延音会让前一个音节延续到下一个音符。

词元	含义
grace	在此音符上演唱
-	延音：让前一个音节延续到此音符（文档规定的形式）
+	同样表示延音
空	同样表示延音——连续两个竖线会产生此项

amazing|-|-|grace|-|how|sweet|the|sound

这会让 “amazing” 跨越第 1-3 个音符演唱，让 “grace” 跨越第 4-5 个音符演唱；同时需要一个恰好包含九个音符的 MIDI 文件。没有休止符词元：应该保持静音的音符不应出现在 MIDI 中。词元数量必须与音符数量相等，且第一个词元必须是一个音节；违反任一规则的歌词字符串都会返回一条指出对应音符的工具错误（“note 1 has no syllable; the first note needs one (position 1)”），且不会上传任何内容。

冷启动

Audial 的 GPU 工作器会缩减至零，因此闲置一段时间后的第一个任务需要额外几分钟来启动工作器并加载模型；之后的每个任务都会很快完成。Audial 会在正在轮询的任务上报告此阶段，每个工具也都会将其作为进度通知和日志行转发：

Warming up the machine — the first request takes a few minutes longer than usual
(about 3 min); every run after this is faster
Working on your job…

Audial 网站、CLI 和插件显示的也是同一句提示。启动任何操作之前，service_status 都能回答同样的问题，因此可以提前解释长时间等待的原因。

哪些内容会离开你的设备

传递给工具的音频和文本会通过 HTTPS 上传到 Audial 的 API（https://api.audialmusic.ai），并在 Audial 的服务器上处理；结果会下载到 AUDIAL_RESULTS_DIR（默认为 ~/Audial）。不会发送其他内容。

如果以下两个文件存在，也会读取它们，因为 Audial SDK 会查找它们： ~/.audial/.audial_config.json，以及启动服务的目录中的 .env 文件。 MCP 客户端配置中的凭据始终优先：audial-mcp 会在 SDK 加载这两个文件之前快照其环境，因此这两个文件都无法重定向你的凭据或 API 主机。

除 list_results 外，所有工具都会调用 Audial API；使用该 API 需要账户拥有有效的 Audial 订阅，否则工具会返回 API 的订阅提示。

配置

变量	必需	默认值
AUDIAL_API_KEY	否	浏览器登录
AUDIAL_USER_ID	否；仅适用于不以 aud_ 开头的旧 API 密钥
AUDIAL_RESULTS_DIR	否	~/Audial
AUDIAL_JOB_TIMEOUT_S	否	900
AUDIAL_API_BASE_URL	否	生产环境 API

许可证

MIT。源代码：https://github.com/AudialAI/audial-mcp