Lets AI agents edit Audionaut multitrack projects by cutting, moving, fading, analyzing, and exporting audio files.
Also known as kvoltmer/Audionaut, audionaut-mcp
- Stars
- 271
- Tools
- 23
- Downloads, 30 days
- —
- Latest version
- 0.5.0
- Last commit
- Nov 15, 2026
- License
- —
What is Audionaut MCP?
Audionaut lets AI agents edit Audionaut multitrack projects by cutting, moving, fading, analyzing, and exporting audio files. It exposes 23 tools, such as get_project_info, create_project, import_audio.
Summary generated from the project's README
About Audionaut MCP server
Audionaut provides an interface for AI agents to perform complex audio engineering tasks within Audionaut multitrack projects. This MCP server acts as a thin wrapper that executes commands via the Audionaut CLI, allowing clients like Claude Desktop or Claude Code to manipulate audio files directly. It supports a wide range of operations including cutting, moving, fading, and analyzing audio, as well as advanced features like stem separation using Demucs models.
To use this server, you must have the Audionaut application installed on macOS, Windows, or Linux. On macOS, the application is sandboxed, so all projects and audio files must reside within the Music folder. The server can interact with an open Audionaut project, treating agent edits as single undo steps in the application's history. This setup allows for a collaborative workflow where the AI performs the heavy lifting of arrangement and editing while the user maintains control over the final project state.
What you can do with it
- 1Batch audio editingYou can ask an AI to split a specific audio clip into segments based on musical bars or beats.
Written from the project's README. Every use case is checked against a quote from it.
How to install Audionaut MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Audionaut MCP in Claude Code
$ claude mcp add audionaut -- npx -y audionaut-mcpInstall Audionaut MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"audionaut": {
"command": "npx",
"args": [
"-y",
"audionaut-mcp"
]
}
}
}Install Audionaut MCP in VS Code
.vscode/mcp.json
{
"servers": {
"audionaut": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"audionaut-mcp"
]
}
}
}Install Audionaut MCP in VS Code CLI
$ code --add-mcp '{"name":"audionaut","type":"stdio","command":"npx","args":["-y","audionaut-mcp"]}'Install Audionaut MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"audionaut": {
"command": "npx",
"args": [
"-y",
"audionaut-mcp"
]
}
}
}Install Audionaut MCP in Codex
$ codex mcp add audionaut -- npx -y audionaut-mcpInstall Audionaut MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.audionaut] command = "npx" args = ["-y", "audionaut-mcp"]
Install Audionaut MCP in Gemini CLI
$ gemini mcp add -s user audionaut npx -- -y audionaut-mcpInstall Audionaut MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"audionaut": {
"command": "npx",
"args": [
"-y",
"audionaut-mcp"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for audionaut-mcp 0.5.0 in an isolated container with no network and no keys. It answered and listed 23 tools.
Audionaut MCP tools 23
Read from the server with tools/listget_project_infoSummarizes an Audionaut project: tempo, tracks, clips with positions/durations and their audio files. Set raw=true for the full persistence JSON instead of the summary.
create_projectCreates a new empty Audionaut project (.audium package) with one track. Fails if the path already exists.
import_audioImports one or more audio files into the project at the given position and saves it. Note: importing creates a new track holding the files.
export_audioRenders the project offline to an audio file (no audio device needed). The output's extension picks the format: .wav (8/16/24/32 bit), .flac (lossless and compressed, 16/24 bit, at most 8 channels per file), .aiff (8/16/24 bit), .ogg (Ogg Vorbis, lossy, at most 8 channels) or .mp3 (lossy, mono or stereo, at most 48 kHz). Lossy formats take bitrate_kbps instead of bit_depth. Pass region to bounce a single region instead - always dry, without any clip's gains or fades. Reports progress in 5% steps when the call carries a progressToken.
analyzeRuns audio analysis (segment boundaries, beats with BPM, onsets) on the project's audio files - or one standalone audio file - and caches the results next to the project for auto_edit/assemble to use. Reports progress as each file and type finishes when the call carries a progressToken.
auto_editSegments a clip on a track using cached analysis results (run analyze first). Splits the clip into musically-aligned regions.
assembleBuilds an arrangement of the given duration from the project's regions, sequentially or at random (requires regions - e.g. from auto_edit).
splitSplits the clip under the given timeline position into two on every track that has one there (the GUI's Split command). Fails with nothing_to_split when no clip spans the position.
create_regionCreates a named region from a timeline range on every track whose clip fully contains it (the GUI's Create Region command). The arrangement itself is unchanged. The name must not be taken by another region (error name_taken).
set_regionRenames a region and/or retrims its source-relative range (clamped to the source audio). Clips have no length of their own, so a retrim affects every clip using the region.
remove_clipRemoves the clip at a timeline position (one clip; ambiguity across tracks needs track), or every placement of a named region. delete_region also drops the region itself unless other clips use it.
move_clipMoves one clip to a new timeline position and/or onto another track. Address it by position (at) or region name; the address must match exactly one clip. to_track takes a track id, or "new" to create a track for it; without to the clip keeps its position. Give at least one of to and to_track.
Show all 23 toolsShow fewer tools
place_clipCreates a new clip from an existing named region at a timeline position, on the track that owns the region (track only disambiguates same-named regions).
cleanup_regionsDeletes every region that has no clip on the timeline (the GUI's Delete Unused Regions). The audio files stay in the package.
clip_gainSets the addressed clip's gain - linear by default, dB with db=true - on every destination channel, or one channel. The address (at or region) must match exactly one clip.
clip_speedSets a clip's playback speed (ratio 0.25-4, 2.0 = double speed, half as long). The mode picks how: repitch (default, varispeed - pitch and length change together) or stretch (pitch-preserving time-stretch). Mode can also be changed on its own. lockTempo ties the clip to the project tempo (speed = project tempo / clip tempo, following tempo changes); the clip tempo is detected by beat tracking or given with `tempo`, which implies the lock.
separate_stemsSplits a clip into Drums/Bass/Other/Vocals tracks with the Demucs (htdemucs) source separator, aligned with the source clip. Slow: minutes for a full song, CPU only; reports progress in 5% steps when the call carries a progressToken. Needs the model weights, which the Audionaut app downloads once (Settings > Separation); fails with model_missing until then, and with demucs_unavailable in builds without Demucs.
clip_fadesSets the addressed clip's fade ramps and curve exponents (0.1-4, 0.5 = equal power). All four fade values are in `unit` (default bars) and 0 clears one. Each ramp has two edges measured inward from the clip edge: the fade-in runs from fade_in_start to fade_in after the clip start, the fade-out from fade_out to fade_out_end before the clip end, so a ramp lasts fade_in - fade_in_start (or fade_out - fade_out_end). A negative offset puts that edge outside the clip, playing source audio beyond it - e.g. fade_out 0.25 with fade_out_end -0.25 (seconds) is a 0.5 s ramp centred on the clip end, the outgoing half of a crossfade. Values are clamped against each other within the clip. The address must match exactly one clip.
remove_trackRemoves a whole track from the project, including its channels, clips and regions. Track ids are positions in the track list, so the ids of the tracks below shift up by one. The audio files stay in the package.
remove_channelRemoves one channel (0-based) from a track, like deleting a channel strip in the GUI. Channel mappings and per-channel clip gains shift down; the audio files stay in the package.
track_panSets the pan position of a track's channel strips, -1 (hard left) to 1 (hard right), 0 centred - the pan slider of the channel view. Every strip of the track by default, one with channel. A mono stem has one strip; a stereo import's two strips start at -1 and 1. Playback and export_audio both follow it; get_project_info shows the current pans per track.
request_featureSends a feature request to the Audionaut maintainer as a GitHub issue. Use it when a task needs something the other tools cannot do: a missing verb or option, a limit that got in the way, or a workflow that took a clumsy workaround. Say what the user was trying to achieve and why the current tools fall short - that context is what makes the request actionable. Tell the user you are sending it; include their name or e-mail only if they offered it. If nothing could be sent, the reply carries a prefilled issue link to hand to the user.
report_bugReports a bug in Audionaut to the maintainer as a GitHub issue. Use it when a tool misbehaves: an error that should not happen, a wrong or inconsistent result, a crash, or a project left in a bad state. Quote the exact tool call and error text - the CLI's code and message - and say what you expected instead; that is what makes the report reproducible. Never include the audio itself, and keep file paths to what is needed. Tell the user you are sending it; include their name or e-mail only if they offered it. If nothing could be sent, the reply carries a prefilled issue link to hand to the user.
Configuration
AUDIONAUT_CLIPath to the Audionaut app binary or audionaut-cli, if it is not found automatically
Automated checks
Ran Nov 16, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work · What to fix for more points
- Source repository linked and reachablekvoltmer/audionaut is public and reachablegithub.com/kvoltmer/audionaut ↗Pass
- Package names this repository as its sourceaudionaut-mcp names kvoltmer/audionaut as sourcenpmjs.com/package/audionaut-mcp ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)No licenseFinding
- Commit or release in the last yearLast commit or release 2026-11-15github.com/kvoltmer/audionaut ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from audionaut-mcpPass
- No critical advisory in the package or its dependencies99 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model23 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledremove_channel has no destructiveHintFinding
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubaudionaut-mcp
An MCP server that lets AI agents (Claude
Code, Claude Desktop, and any other MCP client) edit
Audionaut projects: cut, move, fade, analyse,
auto-edit and export. It is a thin wrapper: every tool runs one Audionaut
command with --json and relays the result — no engine logic lives here.
Requires the Audionaut app (Mac App Store / GitHub Releases). On its own this package does nothing.
Quick start
You need Audionaut — 1.6.3 or later is recommended; 1.6.2 works on macOS and Linux — and Node.js 18 or later.
Claude Code:
claude mcp add audionaut -- npx -y audionaut-mcp
Claude Desktop (claude_desktop_config.json):
{
"mcpServers": {
"audionaut": {
"command": "npx",
"args": ["-y", "audionaut-mcp"]
}
}
}
On Windows, if Claude Desktop cannot start npx, use
"command": "cmd", "args": ["/c", "npx", "-y", "audionaut-mcp"].
Then ask for something like "split the clip in ~/Music/Audionaut/Demo Project.audium every 16 bars". Keep the project open in Audionaut to watch the edits arrive; each one is a single undo step.
On macOS, keep projects in your Music folder. Audionaut is sandboxed
there (App Store and website download alike) and can only reach ~/Music:
projects, audio to import and export targets all have to be inside it, for
example in ~/Music/Audionaut. The server refuses other paths up front with
sandbox_denied and a hint. Windows and Linux have no such limit.
To see which Audionaut the server found and whether it answers:
npx -y audionaut-mcp --check
The server looks for, in order: AUDIONAUT_CLI; a developer build of
audionaut-cli (see the end of this page); audionaut-cli on PATH; the
installed app — /Applications or ~/Applications (or wherever Spotlight
finds it) on macOS, Program Files\Audionaut on Windows, audionaut from
the .deb or an Audionaut*.AppImage in ~/Applications or ~/.local/bin
on Linux. Anywhere else, point AUDIONAUT_CLI at the binary, e.g. your
AppImage.
separate_stems needs the Demucs model, which you download once in the app
(Settings ▸ Separation). The model weights are licensed for research use.
A stem split takes minutes for a full song, and exporting or analysing a long
project can too. When your client sends a progressToken with the call,
separate_stems, export_audio and analyze report progress (Audionaut
1.6.5 and later). A call is only stopped after ten minutes without any sign of
life, not ten minutes in total.
Projects that are open in Audionaut
The tools do not need the user to save first, and they will not write over a
document the user has open. When Audionaut is holding the project, the CLI
hands the command to the app: it acts on the document as the user currently
sees it, unsaved changes included, and the result lands in their undo history
as one step instead of touching Project.json. Saving stays theirs to do.
With no app holding the project, the tools read and write the project file as
they always have. If an app is holding one but cannot be reached, the command
fails (host_unavailable) rather than falling back to the file, which would
be missing whatever is unsaved.
Autosave.json and Host.json inside a package belong to the app — never
read or edit them.
Tools
| Tool | Wraps | Purpose |
|---|---|---|
get_project_info |
info |
Tempo, tracks, clips, files (or the raw persistence JSON) |
create_project |
create |
New empty .audium package |
import_audio |
import |
Add audio files (creates a new track) |
export_audio |
export |
Offline render to WAV, FLAC, AIFF, Ogg Vorbis or MP3 |
analyze |
analyze |
Segment, beat and onset analysis, cached next to the project |
auto_edit |
auto-edit |
Segment a clip using cached analysis |
assemble |
assemble |
Build an arrangement from regions |
split |
split |
Split clips at a timeline position (bars/beats/seconds/clocks) |
create_region |
create-region |
Create a named region from a timeline range |
set_region |
set-region |
Rename and/or retrim a region (affects all its clips) |
remove_clip |
remove-clip |
Remove clip(s) from the timeline |
move_clip |
move-clip |
Move one clip to a new position and/or another track |
place_clip |
place-clip |
Place an existing region on the timeline |
cleanup_regions |
cleanup-regions |
Delete every region no clip uses |
clip_gain |
clip-gain |
Set a clip's gain (linear or dB, all channels or one) |
clip_fades |
clip-fades |
Set a clip's fade lengths, offsets and curves |
clip_speed |
clip-speed |
Set a clip's speed and mode (varispeed or pitch-preserving stretch), or lock it to the project tempo |
remove_track |
remove-track |
Remove a whole track (channels, clips and regions) |
remove_channel |
remove-channel |
Remove one channel from a track |
track_pan |
track-pan |
Pan a track's channel strips, -1 left to 1 right (all strips or one) |
request_feature |
— | Send a feature request to the maintainer (see below) |
report_bug |
— | Send a bug report to the maintainer (see below) |
separate_stems |
separate |
Split a clip into Drums/Bass/Other/Vocals tracks (Demucs; needs the downloaded model) |
A typical agent flow: create_project → import_audio → analyze →
auto_edit/assemble → export_audio. CLI errors come back as tool errors
carrying the CLI's own code: message (e.g. demucs_unavailable: ... in
builds without stem separation), so agents can react.
Feature requests and bug reports from agents
Agents run into the edges of what the tools expose, and into their bugs,
long before a person would file an issue, so two tools give them a direct
channel. request_feature takes a title, a description and (ideally) what
the agent was trying to do and which tool fell short. report_bug takes
the same plus steps to reproduce, the expected behaviour and the project
shape; its description tells agents to quote the exact tool call and error
text and never to attach audio. The server's instructions point agents at
the right one whenever a task needs something the tools cannot do or a tool
misbehaves, and tell them to say so to the user. A reporter name or e-mail
is included only when the user offers one. Both become GitHub issues -
enhancement + agent-request for features, bug + agent-report for
bugs; the reply carries the issue URL and the
feature-request discussion.
Transports, tried in order:
- Relay — the default: a deployment of
Tools/feature-request-relay, a Cloudflare Worker that files the issue with its own GitHub token. This is the path for end users, who have no GitHub credentials on the agent side.AUDIONAUT_FEATURE_REQUEST_URLpoints at another deployment; an empty value skips the relay. - GitHub CLI — when the relay is skipped and
ghis installed and logged in, the issue is filed withgh issue createunder the user's own account (developer machines). - Nothing — otherwise the reply says
sent: falseand carries a prefilled new-issue URL for the user to open themselves.
AUDIONAUT_DISABLE_FEATURE_REQUESTS=1 skips the first two for both tools
(test harnesses, air-gapped setups); the smoke test points the relay URL at
a local stand-in.
Environment variables
| Variable | Effect |
|---|---|
AUDIONAUT_CLI |
Binary that runs the commands: an Audionaut app or audionaut-cli |
AUDIONAUT_SKIP_PATH_CHECK |
1 skips the ~/Music pre-check for the sandboxed macOS app |
AUDIONAUT_DISABLE_ANALYTICS |
1 never sends usage analytics, whatever the app's consent setting |
AUDIONAUT_FEATURE_REQUEST_URL |
Issue relay for request_feature/report_bug; empty skips it |
AUDIONAUT_DISABLE_FEATURE_REQUESTS |
1 never files issues; replies carry a prefilled link instead |
The server sets two variables for every Audionaut it runs, which the open
app uses to group an agent's edits into undo steps: AUDIONAUT_AGENT_SESSION
(one id per server process) and AUDIONAUT_AGENT_TASK (the editing tool's
task parameter). Edits with the same session and task share one undo step
in the user's app, and edits that name no task share one step per session; a
user edit, an undo or ten idle minutes start a new one.
Developing: building the CLI from source
From a clone of the repo, the server prefers a CMake build of the
standalone audionaut-cli, which is not sandboxed:
-
Build the CLI (from the repo root):
cmake -B build -S Audionaut/Catch2Tests cmake --build build -j8 --target AudionautCli -
Install the server's dependencies:
cd Tools/audionaut-mcp && npm install -
Register the checkout instead of the npm package. Claude Code:
claude mcp add audionaut -- node /path/to/Audionaut/Tools/audionaut-mcp/index.jsClaude Desktop: the JSON above with
"command": "node"and"args": ["/path/to/Audionaut/Tools/audionaut-mcp/index.js"].
npm test drives the server through a real MCP client against whichever
binary it finds (AUDIONAUT_CLI picks one). With the sandboxed macOS app it
works in a scratch folder under ~/Music; AUDIONAUT_TEST_DIR overrides
the location.
Paths in tool arguments are best given absolute — relative paths resolve against the server process's working directory, which depends on the MCP client.
Audionaut MCP questions
How do I add Audionaut MCP to Claude Code?
Run claude mcp add audionaut -- npx -y audionaut-mcp in your terminal. Add --scope user to make it available in every project.
How do I add Audionaut MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Audionaut MCP provide?
It exposes 23 tools, including get_project_info, create_project, import_audio, export_audio, analyze.
Where should I store my projects on macOS?
On macOS, you should keep your projects in your Music folder because the sandboxed Audionaut app can only access that directory.
How does the server handle unsaved changes in an open project?
If the Audionaut app is open with a project, the tools act on the document as the user currently sees it, including unsaved changes, and add the edit to the undo history.
Can I split audio into stems?
Yes, the separate_stems tool can split a clip into Drums, Bass, Other, and Vocals using the Demucs model.