MCP Audacity

MCP Audacity is a Codex-ready Audacity control server created by merging, modernizing, and extending two community projects:

• xDarkzx/Audacity-MCP
• An-3/an3-audacity-mcp

It connects Codex to a locally running Audacity instance through Audacity's mod-script-pipe module. This is an independent community project; it is not an official Audacity or OpenAI product.

What is inside

The server exposes tools for:

• project, track, selection, clip, and label management;
• recording and playback transport;
• tone, noise, silence, rhythm, and chirp generation;
• fades, filters, dynamics, loudness, repair, and mastering workflows;
• spectral, loudness, peak, sample-data, and diagnostic analysis;
• audio and label import/export;
• optional local transcription;
• health checks and a static, allow-listed low-level command layer.

The high-level tools validate inputs and return structured results. The low-level layer is deliberately allow-listed: the server does not expose an arbitrary command or free-form Nyquist execution endpoint.

See the complete tool catalog, command status, and live verification reports for details. Verification reports are dated snapshots; plugin-dependent availability can differ between Audacity installations.

Requirements

Before installing, make sure you have:

• Audacity 3.x installed on the same computer as Codex;
• Python 3.10 or newer;
• Git;
• Codex desktop, Codex CLI, or the Codex IDE extension;
• permission to enable Audacity's mod-script-pipe module.

This repository has been developed and tested against Audacity 3.x. Audacity 4.x compatibility is not claimed.

Audacity scripting controls the open application directly and supports one active project at a time. Keep Audacity visible while testing so you can inspect changes and respond to dialogs. Do not run this server on a public server or an untrusted shared machine: any local process able to reach the scripting pipe may control Audacity. Read the Audacity scripting manual before enabling the module.

Installation

1. Clone the repository

git clone https://github.com/illia3/MCP-Audacity.git
cd MCP-Audacity

2. Create a virtual environment and install the server

Windows PowerShell:

py -m venv .venv
.\.venv\Scripts\python -m pip install --upgrade pip
.\.venv\Scripts\python -m pip install -e .

macOS or Linux:

python3 -m venv .venv
./.venv/bin/python -m pip install --upgrade pip
./.venv/bin/python -m pip install -e .

Optional local transcription support:

# Windows
.\.venv\Scripts\python -m pip install -e ".[transcription]"

# macOS or Linux
./.venv/bin/python -m pip install -e ".[transcription]"

Transcription dependencies and models require additional disk space and memory. A model may be downloaded the first time transcription is used.

3. Enable Audacity scripting

1. Open Audacity.
2. On Windows or Linux, open Edit > Preferences > Modules. On macOS, open Audacity > Preferences > Modules.
3. Set mod-script-pipe to Enabled.
4. Confirm the change and restart Audacity manually.
5. Reopen the Modules page and confirm that the module is still enabled.

The module normally ships with Audacity on Windows and macOS but is disabled by default. Linux package availability varies; if it is missing, install a package or build of Audacity that includes mod-script-pipe.

4. Add the server to Codex

Use absolute paths when possible. Replace the example path with the location of your clone.

With Codex CLI on Windows:

codex mcp add audacity -- "C:\path\to\MCP-Audacity\.venv\Scripts\python.exe" -m audacity_mcp.main

With Codex CLI on macOS or Linux:

codex mcp add audacity -- "/absolute/path/to/MCP-Audacity/.venv/bin/python" -m audacity_mcp.main

Verify the registration:

codex mcp list

Alternatively, add a project-scoped .codex/config.toml to a trusted clone.

Windows example:

[mcp_servers.audacity]
command = "C:\\path\\to\\MCP-Audacity\\.venv\\Scripts\\python.exe"
args = ["-m", "audacity_mcp.main"]
cwd = "C:\\path\\to\\MCP-Audacity"
startup_timeout_sec = 20
tool_timeout_sec = 600
enabled = true
required = false
default_tools_approval_mode = "writes"

macOS or Linux example:

[mcp_servers.audacity]
command = "/absolute/path/to/MCP-Audacity/.venv/bin/python"
args = ["-m", "audacity_mcp.main"]
cwd = "/absolute/path/to/MCP-Audacity"
startup_timeout_sec = 20
tool_timeout_sec = 600
enabled = true
required = false
default_tools_approval_mode = "writes"

In the Codex desktop app, open Settings > MCP servers > Add server, enter the name and STDIO command, save, and restart Codex. Codex desktop, CLI, and the IDE extension share MCP configuration on the same host. See the official Codex MCP documentation for current configuration details.

5. Verify the connection

1. Start Audacity and open or create one project.
2. Restart Codex after adding the server.
3. Use /mcp in Codex to confirm that audacity is active.
4. Ask Codex: Run audacity_health and show the result.
5. Then try the read-only request: Run project_get_info and summarize the open Audacity project.

Only begin editing after the health check succeeds. Use a disposable project for your first write test.

What to expect when using it

Codex starts this repository as a local STDIO MCP server. The server then sends validated commands to the currently running Audacity process through named pipes. Successful write operations appear immediately in Audacity, so you can watch and intervene between tool calls.

Important behavior:

• keep one Audacity instance and one active project open;
• save a backup before destructive or multi-step edits;
• avoid manual timeline changes while a tool call is running;
• modal dialogs can block scripting until they are closed;
• effects and analyzers vary by Audacity version, build, installed plugins, and localization;
• use explicit export paths and a new filename when you do not want to replace an existing file;
• a multi-step workflow is composed of separate MCP calls, so inspect the project between steps when precision matters.

Suggested first prompts:

Check Audacity health and summarize the current project without changing it.

List all tracks, their types, mute/solo state, and approximate duration.

In a new disposable project, generate a short 880 Hz tone on its own track and keep the peak below -6 dBFS.

Analyze the current selection and recommend a cleanup chain, but do not apply any effects yet.

Troubleshooting

If audacity_health cannot connect:

• confirm that Audacity is already running;
• confirm that mod-script-pipe is enabled, then restart Audacity;
• keep only one Audacity instance open;
• restart Codex after changing MCP configuration;
• confirm that Codex, Python, and Audacity are running on the same machine and user session;
• check local security software and file permissions.

If a specific command is unavailable, its effect, analyzer, or plugin may not be included in your Audacity build. Check command status, install or enable the required plugin, restart Audacity, and run the health check again.

If a command appears stuck, bring Audacity to the foreground and close any modal dialog. Then retry the operation.

Development and verification

Install development dependencies and run the offline suite:

python -m pip install -e ".[dev]"
python -m pytest -q

With Audacity running and mod-script-pipe enabled, run the live integration suite:

python scripts/live_integration_test.py

The live suite edits the current Audacity project. Use a disposable project and review the script before running it.

Attribution and license

MCP Audacity incorporates and extends work from both upstream repositories named above. See THIRD_PARTY_NOTICES.md for attribution details.

Released under the Apache License 2.0.