# MCP Audacity

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

- [xDarkzx/Audacity-MCP](https://github.com/xDarkzx/Audacity-MCP)
- [An-3/an3-audacity-mcp](https://github.com/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](docs/TOOLS.md), [command status](docs/COMMAND_STATUS.md), and [live verification reports](docs/) 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](https://manual.audacityteam.org/man/scripting.html) before enabling the module.

## Installation

### 1. Clone the repository

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

### 2. Create a virtual environment and install the server

Windows PowerShell:

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

macOS or Linux:

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

Optional local transcription support:

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

```bash
# 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:

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

With Codex CLI on macOS or Linux:

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

Verify the registration:

```text
codex mcp list
```

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

Windows example:

```toml
[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:

```toml
[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](https://developers.openai.com/codex/mcp/) 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:

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

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

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

```text
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](docs/COMMAND_STATUS.md), 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:

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

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

```text
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](THIRD_PARTY_NOTICES.md) for attribution details.

Released under the [Apache License 2.0](LICENSE).