Gizmos Audacity README

Gizmos Audacity MCP

Local MCP tools for editing, processing and measuring audio in Audacity.

45 typed tools · Audacity 3.7.x · Node 24.21+ · stdio

Import audio, edit tracks and clips, apply effects, write labels, export mixes, and measure peak/RMS or optional LUFS/true peak. Audacity does the processing. Windows supports hidden windows and native dialog recovery. macOS/Linux support the scripting FIFOs; their native window lifecycle is not qualified.

Requirements

• English Audacity 3.7.x with mod-script-pipe enabled: 3.7.8 is the reference build (bundled catalogue, parameter limits, source audit) and 3.7.9 is verified; other patch levels are refused until verified. On Windows, install and pin it: winget install --id Audacity.Audacity -e --version 3.7.8, then winget pin add --id Audacity.Audacity -e --version 3.7.8.
• Audacity 4 is not supported: 4.0 removed the scripting interface (mod-script-pipe). Support would be reconsidered only if Audacity ships a scripting host with full control.
• Node.js 24.21 or newer, running as the same user as Audacity.
• Optional ffmpeg/ffprobe for LUFS, LRA, true peak, other file formats and metadata. Native PCM/float WAV measurement needs neither.

Quick start

The npm package is @gizmos-quest/audacity-mcp. For a source checkout, run npm ci, then npm run build; use node dist/main.js as the server command.

1. Install Audacity 3.7.8. Enable mod-script-pipe in Preferences → Modules, choose English in Preferences → Interface, and turn off Preferences → Application → Check for updates (update notices are modal and block scripting until closed). Restart Audacity.

2. Check setup:

   TerminalCopy

   npx -y @gizmos-quest/audacity-mcp doctor
   

   With Audacity stopped, doctor --fix can enable the scripting module. It saves a config backup first. Setup and configuration.

3. Add the local server to your client using a snippet below, then restart the client if it requires that. Keep one server in control of the shared pipe.

Clients

Claude Code

claude mcp add --scope user --transport stdio audacity -- npx -y @gizmos-quest/audacity-mcp

Claude Desktop / Cursor — add this to the client's MCP configuration:

{
  "mcpServers": {
    "audacity": {
      "command": "npx",
      "args": ["-y", "@gizmos-quest/audacity-mcp"]
    }
  }
}

VS Code — .vscode/mcp.json:

{
  "servers": {
    "audacity": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@gizmos-quest/audacity-mcp"]
    }
  }
}

Codex — ~/.codex/config.toml:

[mcp_servers.audacity]
command = "npx"
args = ["-y", "@gizmos-quest/audacity-mcp"]
startup_timeout_sec = 90
tool_timeout_sec = 900

Effects can take ten minutes; allow a longer client tool timeout. See client setup for official references and Windows command resolution. Troubleshooting covers missing pipes and localized plugin IDs.

First prompt

Check Audacity's status and launch it if stopped. Import my voice recording as Voice. Measure it, then show a dry-run voice cleanup plan without normalization or noise reduction. Ask before applying it and save a project backup first.

A pipeline preview takes a named or zero-based track reference:

{"track":"Voice","preset":"voice","dryRun":true,"loudness":"none"}

Try the reproducible voice-over example: generated audio, reviewed cleanup, a ducked bed, chapters/subtitles and measured delivery. Its opt-in runner drives the built server over stdio against live Audacity.

Tools

Every name starts with audacity_. Tool reference includes arguments and units; the capability matrix lists limits.

Safety

• Save a new .aup3 backup before destructive processing. Scripted effects do not create individual undo entries. Existing project save paths are refused.
• Strict inputs and a reviewed catalogue block known modal commands. Hidden Audacity still runs its UI and audio engine; it has no native headless mode.
• A timeout can leave an edit completed or still running. Inspect dialogs, use explicit recovery, then inspect the project before deciding what to do.
• Noise reduction requires fresh process state and an explicit room-tone capture; normalization, limiting and timing changes stay explicit.
• mod-script-pipe trusts local processes running as your user. Use one controller. The server never downloads runtimes/models or kills Audacity.

Native safety limits · Effect requirements · Testing · Architecture · Contributing · Security

MIT licensed. Research and source attribution are in NOTICE.md. Audacity is a trademark of Muse Group; this project is unaffiliated.