Audionaut

audionaut-mcp

一个 MCP 服务，让 AI Agent（Claude Code、Claude Desktop 和其他 MCP 客户端）编辑 Audionaut 项目：剪切、移动、淡入淡出、分析、 自动编辑和导出。它只是一个轻量封装：每个工具都会运行一条带有 --json 的 Audionaut 命令并转发结果——这里不包含任何引擎逻辑。

需要 Audionaut 应用（Mac App Store / GitHub Releases）。此软件包单独使用 没有任何作用。

快速开始

你需要 Audionaut——建议使用 1.6.3 或更高版本；1.6.2 可在 macOS 和 Linux 上运行——以及 Node.js 18 或更高版本。

Claude Code：

claude mcp add audionaut -- npx -y audionaut-mcp

Claude Desktop（claude_desktop_config.json）：

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

在 Windows 上，如果 Claude Desktop 无法启动 npx，请使用 "command": "cmd", "args": ["/c", "npx", "-y", "audionaut-mcp"]。

然后提出类似 “每隔 16 小节拆分 ~/Music/Audionaut/Demo Project.audium 中的片段” 的请求。保持项目在 Audionaut 中打开，即可查看编辑结果；每次编辑都对应一个撤销步骤。

在 macOS 上，请将项目保存在 Music 文件夹中。 Audionaut 在该文件夹中运行于沙盒环境（无论是从 App Store 还是网站下载），且只能访问 ~/Music： 项目、要导入的音频以及导出目标都必须位于其中， 例如 ~/Music/Audionaut。服务器会提前拒绝其他路径，并返回 sandbox_denied 提示。Windows 和 Linux 没有此限制。

要查看服务器找到的是哪个 Audionaut，以及它是否能正常响应：

npx -y audionaut-mcp --check

服务器会按以下顺序查找：AUDIONAUT_CLI；开发者构建的 audionaut-cli（见本页末尾）；PATH 中的 audionaut-cli；已安装的应用——macOS 上的 /Applications 或 ~/Applications（或 Spotlight 找到的位置），Windows 上的 Program Files\Audionaut，Linux 上的 .deb 提供的 audionaut，或 ~/Applications 或 ~/.local/bin 中的 Audionaut*.AppImage。如果位于其他位置，请将 AUDIONAUT_CLI 指向该二进制文件，例如你的 AppImage。

separate_stems 需要 Demucs 模型，你可以在应用中下载一次（Settings ▸ Separation）。该模型权重仅获准用于研究。

完整歌曲的分轨需要几分钟，导出或分析大型项目也可能需要几分钟。当客户端在调用时发送 progressToken， separate_stems、export_audio 和 analyze 会报告进度（Audionaut 1.6.5 及更高版本）。只有连续十分钟没有任何响应时，调用才会停止，而非总共运行十分钟后停止。

在 Audionaut 中打开的项目

工具不需要用户先保存，也不会覆盖用户已打开的文档。当 Audionaut 正在持有项目时，CLI 会将命令交给应用处理：它会针对用户当前看到的文档执行操作，包括未保存的更改；结果会作为一个步骤进入撤销历史，而不会触碰 Project.json。是否保存仍由用户决定。

如果没有应用持有项目，工具就像以往一样读写项目文件。如果应用正持有项目但无法连接，命令会失败（host_unavailable），而不会退回到文件操作，因为文件中不会包含任何未保存的内容。

软件包中的 Autosave.json 和 Host.json 属于应用——切勿读取或编辑它们。

工具

工具	封装命令	用途
get_project_info	info	节奏、音轨、片段、文件（或原始持久化 JSON）
create_project	create	新建空的 .audium 包
import_audio	import	添加音频文件（会创建新音轨）
export_audio	export	离线渲染为 WAV、FLAC、AIFF、Ogg Vorbis 或 MP3
analyze	analyze	分析分段、节拍和起音，结果缓存在项目文件旁
auto_edit	auto-edit	使用缓存的分析结果对片段进行分段
assemble	assemble	根据区域构建编排
split	split	在时间线位置（小节／节拍／秒／时钟）分割片段
create_region	create-region	根据时间线范围创建命名区域
set_region	set-region	重命名和／或重新修剪区域（会影响其所有片段）
remove_clip	remove-clip	从时间线移除片段
move_clip	move-clip	将片段移至新位置和／或另一条音轨
place_clip	place-clip	将现有区域放置到时间线上
cleanup_regions	cleanup-regions	删除所有未被任何片段使用的区域
clip_gain	clip-gain	设置片段增益（线性或 dB，可应用于所有声道或单个声道）
clip_fades	clip-fades	设置片段淡入淡出的长度、偏移和曲线
clip_speed	clip-speed	设置片段速度和模式（变速播放或保留音高的拉伸），或将其锁定到项目节奏
remove_track	remove-track	移除整条音轨（声道、片段和区域）
remove_channel	remove-channel	从音轨中移除一个声道
track_pan	track-pan	设置音轨各通道条的声像，-1 为左，1 为右（所有通道条或单个通道条）
request_feature	—	向维护者发送功能请求（见下文）
report_bug	—	向维护者提交错误报告（见下文）
separate_stems	separate	将片段拆分到鼓／贝斯／其他／人声音轨（Demucs；需要已下载的模型）

典型的 Agent 工作流：create_project → import_audio → analyze → auto_edit／assemble → export_audio。CLI 错误会作为工具错误返回，并包含 CLI 自身的 code: message（例如，在未构建音轨分离功能的版本中会返回 demucs_unavailable: ...），以便 Agent 作出响应。

来自 Agent 的功能请求和错误报告

Agent 会比人更早遇到工具功能的边界和错误，因此我们提供了两个工具，让它们可以直接反馈。request_feature 接受标题、描述，以及（最好提供）Agent 尝试执行的操作和未能满足需求的工具。report_bug 接受相同的信息，外加复现步骤、预期行为和项目情况；其描述会告诉 Agent 引用确切的工具调用和错误文本，且绝不要附加音频。只要任务需要工具无法完成的操作，或工具出现异常，服务的说明就会引导 Agent 使用正确的工具，并要求它们告知用户。只有在用户主动提供时，才会附上 reporter 名称或电子邮件地址。两种反馈都会转为 GitHub issue：功能请求使用 enhancement + agent-request，错误报告使用 bug + agent-report；回复中会附上 issue URL 和功能请求讨论。

按以下顺序尝试传输方式：

1. 中继 — 默认方式：部署 Tools/feature-request-relay，这是一个使用自身 GitHub token 创建 issue 的 Cloudflare Worker。此方式面向最终用户，因为他们在 Agent 端没有 GitHub 凭据。AUDIONAUT_FEATURE_REQUEST_URL 可指向其他部署；值为空时会跳过中继。
2. GitHub CLI — 跳过中继且已安装并登录 gh 时，使用用户自己的账户通过 gh issue create 创建 issue（开发者机器）。
3. 无 — 其他情况下，回复会显示 sent: false，并附上已预填内容的新 issue URL，供用户自行打开。

AUDIONAUT_DISABLE_FEATURE_REQUESTS=1 会为这两个工具跳过前两种方式（用于测试框架、隔离网络环境）；冒烟测试会将中继 URL 指向本地替代服务。

环境变量

变量	效果
AUDIONAUT_CLI	用于运行命令的二进制文件：Audionaut 应用或 audionaut-cli
AUDIONAUT_SKIP_PATH_CHECK	设为 1 时，跳过针对沙盒化 macOS 应用的 ~/Music 预检查
AUDIONAUT_DISABLE_ANALYTICS	设为 1 时，无论应用的许可设置如何，都不会发送使用情况分析数据
AUDIONAUT_FEATURE_REQUEST_URL	request_feature/report_bug 使用的 issue 中继；值为空时跳过
AUDIONAUT_DISABLE_FEATURE_REQUESTS	设为 1 时，不会创建 issue；回复中会附上已预填内容的链接

服务为其启动的每个 Audionaut 设置两个变量，已打开的应用会用它们将 Agent 的编辑操作分组为撤销步骤：AUDIONAUT_AGENT_SESSION（每个服务进程一个 ID）和 AUDIONAUT_AGENT_TASK（编辑工具的 task 参数）。具有相同 session 和 task 的编辑会在用户的应用中共享一个撤销步骤；未指定 task 的编辑则每个 session 共用一个撤销步骤。用户编辑、撤销操作或十分钟的空闲时间都会开始新的步骤。

开发：从源代码构建 CLI

克隆仓库后，服务会优先使用 CMake 构建独立的 audionaut-cli，它不受沙盒限制：

1. 构建 CLI（在仓库根目录下）：

   cmake -B build -S Audionaut/Catch2Tests
   cmake --build build -j8 --target AudionautCli
   

2. 安装服务的依赖项：

   cd Tools/audionaut-mcp && npm install
   

3. 注册本地检出版本，而不是 npm 包。Claude Code：

   claude mcp add audionaut -- node /path/to/Audionaut/Tools/audionaut-mcp/index.js
   

   Claude Desktop：使用上面的 JSON，将 "command": "node" 和 "args": ["/path/to/Audionaut/Tools/audionaut-mcp/index.js"] 作为配置。

npm test 会通过真实的 MCP 客户端驱动服务，并使用找到的任意二进制文件（由 AUDIONAUT_CLI 指定）。使用沙盒化 macOS 应用时，测试会在 ~/Music 下的临时文件夹中运行；AUDIONAUT_TEST_DIR 可覆盖该位置。

工具参数中的路径最好使用绝对路径——相对路径会相对于服务进程的工作目录解析，而该目录取决于 MCP 客户端。