Gizmos Audacity

What Gizmos Audacity MCP server does

The Gizmos Audacity MCP server gives an MCP client structured control over a local Audacity installation. It can import recordings, create or modify tracks, edit clips, apply effects, generate audio, write labels, export mixes, and inspect project state. Measurement tools cover peak and RMS values, while optional ffmpeg and ffprobe support enables LUFS, loudness range, true peak, additional file formats, and metadata inspection.

The tool set contains 45 typed operations. These include session and discovery controls, project and track editing, processing pipelines, label management, transport controls, file comparison, silence and contrast checks, and project recovery actions. Every exposed tool uses an audacity_ prefix.

How it works

The server communicates with Audacity through mod-script-pipe; Audacity performs the editing and analysis rather than the MCP process. The server uses stdio as its MCP transport and must run as the same user as Audacity. Audacity does not provide a native headless mode here, so even hidden-window operation still relies on its user interface and audio engine.

The Gizmos Audacity MCP server supports Audacity 3.7.x only, with 3.7.8 as the reference build and 3.7.9 verified. Audacity 4 is unsupported because it removed the scripting interface used by this integration. The Audacity interface must be set to English, and update notices should be disabled because modal dialogs can block scripting.

Safety behavior includes strict inputs, a reviewed command catalogue, explicit destructive operations, and project-backup handling. Scripted effects do not create separate undo entries. A timeout may mean an operation completed or remains in progress, so callers should inspect dialogs and project state before retrying. Only one controller should use the shared scripting pipe at a time.

Setup and configuration

Install Node.js 24.21 or newer, then install the npm package @gizmos-quest/audacity-mcp, or build a source checkout with npm ci followed by npm run build. A source installation runs with node dist/main.js; the package can be launched with npx -y @gizmos-quest/audacity-mcp.

Enable mod-script-pipe in Audacity's Modules preferences and restart Audacity. The doctor command checks the setup, while doctor --fix can enable the scripting module when Audacity is stopped and saves a configuration backup first. Configure the MCP client with the server's stdio command, then restart the client if required. Client examples are provided for Claude Code, Claude Desktop, Cursor, VS Code, and Codex.

Optional ffmpeg and ffprobe are needed for LUFS, loudness range, true peak, some other formats, and metadata operations. Native PCM or float WAV measurement does not require them. On Windows, hidden-window and native-dialog recovery are supported; the native window lifecycle is not qualified on macOS or Linux.

Tools and capabilities

• Launch, stop, inspect, recover, and query Audacity sessions and dialogs.
• Import, export, select, edit, move, and modify tracks and clips.
• Apply effects, fades, envelopes, noise profiles, pipelines, ducking, macros, and batches.
• Create and inspect labels, label files, regions, and exported label data.
• Measure audio, compare files, inspect silence and contrast, and evaluate loudness targets.
• Manage transport, history, preferences, project information, and capability discovery.

The server can preview a processing pipeline before applying it. Noise reduction requires a fresh process state and explicit room-tone capture; normalization, limiting, and timing changes remain explicit operations.

Limitations and notes

The Gizmos Audacity MCP server is tied to Audacity 3.7.x and the English interface. Audacity 4 is not supported. The scripting pipe trusts local processes running under the current user, so local access should be treated accordingly. The server does not download runtimes or models and does not terminate Audacity.

Create a new .aup3 backup before destructive processing. Existing project save paths are refused by the safety behavior described in the project documentation. Effects may take up to several minutes, so clients should allow extended tool timeouts; the supplied Codex example uses a 900-second tool timeout. If a command times out, inspect the current project and dialogs instead of assuming it failed.