Audionaut

audionaut-mcp

AI エージェント（Claude Code、Claude Desktop、その他の MCP クライアント）が Audionaut プロジェクトを編集できるようにする MCP サーバーです。カット、移動、フェード、分析、自動編集、エクスポートに対応しています。薄いラッパーであり、各ツールは --json を付けて Audionaut のコマンドを 1 つ実行し、その結果を中継します。エンジンのロジックはここにはありません。

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"] を使用してください。

次のように依頼してみてください。「~/Music/Audionaut/Demo Project.audium のクリップを 16 小節ごとに分割して」。Audionaut でプロジェクトを開いたままにしておくと、編集内容が反映されるのを確認できます。各編集は 1 回の取り消し操作になります。

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 が対象です。それ以外の場所にある場合は、たとえば AppImage を指定するように AUDIONAUT_CLI を設定してください。

separate_stems には Demucs モデルが必要です。アプリの「設定 ▸ 分離」で一度ダウンロードしてください。モデルの重みは研究目的での使用を対象とするライセンスです。

ステム分離は、1 曲全体の場合は数分かかります。長いプロジェクトのエクスポートや分析にも時間がかかることがあります。クライアントが呼び出し時に progressToken を送信すると、separate_stems、export_audio、analyze は進捗を報告します（Audionaut 1.6.5 以降）。呼び出しが停止されるのは、合計 10 分経過したときではなく、10 分間まったく応答がない場合です。

Audionaut で開いているプロジェクト

ツールを使う前にユーザーが保存する必要はありません。また、ユーザーが開いているドキュメントに上書きすることもありません。Audionaut がプロジェクトを保持している場合、CLI はコマンドをアプリに渡します。未保存の変更も含め、ユーザーが現在見ているドキュメントに対して処理を実行し、Project.json に触れる代わりに、結果を取り消し履歴の 1 ステップとして記録します。保存はユーザーが行います。

プロジェクトを保持するアプリがない場合、ツールはこれまでどおりプロジェクトファイルを読み書きします。アプリがプロジェクトを保持しているものの、接続できない場合は、コマンドは 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、全チャンネルまたは1つ）
clip_fades	clip-fades	クリップのフェードの長さ、オフセット、カーブを設定
clip_speed	clip-speed	クリップの速度とモード（バリスピードまたはピッチを保持するストレッチ）を設定するか、プロジェクトのテンポに固定
remove_track	remove-track	トラック全体（チャンネル、クリップ、リージョン）を削除
remove_channel	remove-channel	トラックからチャンネルを1つ削除
track_pan	track-pan	トラックのチャンネルストリップをパン（-1 が左、1 が右。すべてのストリップまたは1つ）
request_feature	—	メンテナーに機能リクエストを送信（下記参照）
report_bug	—	メンテナーにバグレポートを送信（下記参照）
separate_stems	separate	クリップを Drums／Bass／Other／Vocals の各トラックに分割（Demucs。ダウンロード済みモデルが必要）

一般的なエージェントのワークフロー：create_project → import_audio → analyze → auto_edit／assemble → export_audio。CLI エラーは、CLI 独自の code: message（たとえば、ステム分離のないビルドでは demucs_unavailable: ...）を含むツールエラーとして返されるため、エージェントはそれに応じて対処できます。

エージェントからの機能リクエストとバグ報告

エージェントは、人が課題を報告するよりずっと前に、ツールで公開されている機能の限界やバグに遭遇します。そのため、エージェントが直接報告できる手段を2つ用意しています。request_feature では、タイトル、説明、そして（できれば）エージェントが何をしようとしていたのか、どのツールでは不十分だったのかを受け取ります。report_bug では、同じ情報に加え、再現手順、期待する動作、プロジェクトの構成を受け取ります。説明では、エージェントにツール呼び出しとエラー文を正確に引用し、音声は添付しないよう伝えます。タスクにツールでできないことが必要な場合や、ツールが正常に動作しない場合、サーバーの指示はエージェントに適切な方を案内し、その旨をユーザーに伝えるよう指示します。reporter の名前またはメールアドレスは、ユーザーから提示された場合にのみ含めます。どちらも GitHub の課題として登録されます。機能リクエストには enhancement + agent-request、バグ報告には bug + agent-report が付与されます。返信には課題の URL と機能リクエストのディスカッションが含まれます。

トランスポートは、次の順に試されます。

1. リレー — デフォルトです。Tools/feature-request-relay のデプロイを利用します。これは、独自の GitHub トークンで課題を登録する Cloudflare Worker です。エージェント側に GitHub の認証情報がないエンドユーザー向けの方法です。AUDIONAUT_FEATURE_REQUEST_URL で別のデプロイ先を指定できます。値が空の場合はリレーをスキップします。
2. GitHub CLI — リレーがスキップされ、gh がインストール済みでログインしている場合は、ユーザー自身のアカウントで gh issue create を使って課題を登録します（開発者のマシン向け）。
3. なし — それ以外の場合、返信には sent: false と、ユーザーが自分で開ける新しい課題の入力済み URL が含まれます。

AUDIONAUT_DISABLE_FEATURE_REQUESTS=1 を設定すると、どちらのツールでも最初の2つをスキップします（テストハーネス、エアギャップ環境向け）。スモークテストでは、リレー 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 の課題リレー。空の場合はスキップします
AUDIONAUT_DISABLE_FEATURE_REQUESTS	1 の場合、課題を一切登録せず、返信に入力済みリンクを含めます

サーバーは実行する Audionaut ごとに2つの変数を設定します。オープンアプリはこれらを使ってエージェントによる編集を取り消しステップにまとめます。AUDIONAUT_AGENT_SESSION（サーバープロセスごとに1つの ID）と AUDIONAUT_AGENT_TASK（編集ツールの task パラメーター）です。同じセッションとタスクで行われた編集は、ユーザーのアプリで1つの取り消しステップにまとめられます。タスク名が指定されていない編集は、セッションごとに1ステップにまとめられます。ユーザーによる編集、取り消し、または10分間のアイドル状態があると、新しいステップが始まります。

開発：ソースから CLI をビルドする

リポジトリをクローンすると、サーバーはサンドボックス化されていないスタンドアロンの audionaut-cli を CMake でビルドして使用します。

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 は、見つかったバイナリ（AUDIONAUT_CLI で選択）を使い、実際の MCP クライアント経由でサーバーをテストします。サンドボックス化された macOS アプリの場合、~/Music 内の一時フォルダーで動作します。AUDIONAUT_TEST_DIR で場所を変更できます。

ツール引数のパスには、絶対パスを指定するのがおすすめです。相対パスはサーバープロセスの作業ディレクトリを基準に解決されますが、これは MCP クライアントによって異なります。