audacity-mcp-max

audacity-mcp-max

AI-powered audio editing in Audacity through the Model Context Protocol

Quick Start • Why audacity-mcp-max? • Pipelines • Tool Reference • Troubleshooting

audacity-mcp-max connects any MCP-compatible AI assistant to Audacity, giving it full control over audio editing through 132 tools spanning effects, cleanup, mastering, transcription, and more. Talk to your AI assistant and it edits your audio in real-time.

No cloud. No API keys for audio processing. Everything runs locally through Audacity's named pipe interface.

Compatibility: audacity-mcp-max currently works with Audacity 3.x only. Audacity 4.x is not yet supported — we hope to add support in the future.

Works With

audacity-mcp-max works with any AI client that supports the Model Context Protocol:

• Claude Desktop — Anthropic's desktop app
• Claude Code — CLI agent
• Cursor — AI code editor with MCP support
• Any other MCP-compatible client

Quick Start

1. Get audacity-mcp-max

Claude Code plugin (recommended - macOS and Linux only)

Windows: the plugin's launcher is a POSIX shell script and cannot starton Windows. Skip straight to Step 2and use install.bat.

/plugin marketplace add robworks-code/robworks-claude-code-plugins
/plugin install audacity@robworks-claude-code-plugins

Then run /audacity:setup. It checks the parts people get wrong - uv,mod-script-pipe, whether Audacity needs to be closed before its config can bechanged - and finishes by verifying a real round trip. Needsuv; no pip step and nothing to add to your MCPclient config. It replaces step 2 below - do not also run the installer, whichwould install a second copy through pip. Once /audacity:setup finishes, gostraight to Start editing.

Without the plugin, get the source first:

Option A: Click the green Code button above → Download ZIP → extract to a folder

Option B: Clone with git:

git clone https://github.com/robworks-code/audacity-mcp-max.git

2. Run the installer (sets up everything else automatically)

Open the folder and run:

• Windows: Double-click install.bat
• macOS / Linux: Open terminal in the folder and run bash install.sh

The installer does 3 things: installs audacity-mcp-max from GitHub, enables mod-script-pipe in Audacity, and configures Claude Desktop — no manual JSON editing needed.

If you're not using Claude Desktop, install manually with pip install git+https://github.com/robworks-code/audacity-mcp-max.git and add to your client's MCP config:

{
  "mcpServers": {
    "audacity": {
      "command": "audacity-mcp-max"
    }
  }
}

Check your client's MCP documentation for the config file location.

3. Start editing

Open Audacity, load some audio, then talk to your AI:

"Clean up this podcast recording"
"Master this track for Spotify, it's EDM"
"Transcribe this and add labels at each sentence"
"Add reverb with a large room, then export as FLAC"

Audacity must be open first. audacity-mcp-max communicates through Audacity's named pipe — it can't launch Audacity for you.

See the full Installation Guide for detailed setup on all platforms and MCP clients.

Why audacity-mcp-max?

Without audacity-mcp-max: You manually navigate menus, tweak effect parameters by ear, apply effects one at a time, look up ACX specs, and repeat until it sounds right.

With audacity-mcp-max: You describe what you want in plain English and the AI handles the rest — picking the right effects, setting industry-standard parameters, and chaining operations together.

audacity-mcp-max is especially useful for:

• Podcasters who want consistent, professional sound without audio engineering knowledge
• Musicians who need quick mastering with genre-appropriate settings
• Content creators working with interviews, voiceovers, or field recordings
• Anyone who'd rather describe what they want than click through menus

What Can It Do?

You:  "Clean up this podcast recording"
AI:   Runs auto_cleanup_podcast → HPF 80Hz → noise reduction → compression → safe loudness check

You:  "Master this track for Spotify, it's EDM"
AI:   Runs auto_master_music style=edm → HPF 30Hz → click removal → compression 2.5:1 → bass +2dB → loudness check

You:  "This is a noisy live recording, fix it up"
AI:   Runs auto_cleanup_live → HPF 100Hz → click removal → noise reduction 18dB → compression 5:1

You:  "Transcribe this interview and add labels"
AI:   Runs transcribe_to_labels → faster-whisper transcription → Audacity labels at each timestamp

You:  "Add reverb to the vocals, then export as FLAC"
AI:   select region → reverb effect → export to FLAC

Features

132 Tools Across 11 Categories

Pipelines

audacity-mcp-max includes 9 one-click pipelines for common audio tasks. Each pipeline is designed to be safe for badly recorded audio — it will never boost your audio dangerously. Pipelines clean up and improve your audio, then you can manually adjust loudness afterward if needed.

How Pipelines Work

1. You tell the AI what you want (e.g. "clean up this podcast")
2. The AI picks the right pipeline and starts it
3. The pipeline runs in the background — you get a job_id back
4. Poll with check_pipeline_status every 15-30 seconds to monitor progress
5. When done, a popup appears in Audacity

Safety rule: Pipelines only reduce peaks if they're too hot. They never boost loudness. If you want to hit a specific LUFS target (e.g. -14 for Spotify), ask the AI to run loudness_normalize after you've checked the results look good.

Pipeline Reference

auto_analyze_audio — Analyze before processing

Measures your audio and recommends the best pipeline. Run this first if you're not sure what to do.

You: "Analyze this audio"
→ Returns: peak level, noise floor, clipping status, recommended pipeline

auto_cleanup_audio — Safe cleanup only

Cleans up noise and artifacts without changing loudness at all. Use when levels are already fine.

You: "Just clean up the noise, don't change the volume"
→ DC offset removal → HPF 80Hz → noise reduction → click removal (optional)

auto_cleanup_podcast — Podcast / voiceover

Professional broadcast processing for spoken word.

You: "Clean up this podcast recording"
→ DC offset → HPF 80Hz → noise reduction 12dB → compression 3:1 → safe loudness check

auto_audiobook_mastering — Audiobook (ACX/Audible)

Targets ACX requirements for audiobook distribution.

You: "Master this for ACX / Audible"
→ DC offset → HPF 80Hz → noise reduction 12dB → compression 2.5:1 → safe loudness check → peak cap -3dB

auto_cleanup_interview — Interview / dialogue

Light touch for conversations — preserves natural dynamics.

You: "Clean up this interview recording"
→ DC offset → HPF 80Hz → noise reduction 8dB → compression 2.5:1 → safe loudness check

auto_cleanup_vocal — Singing / studio vocal

Tuned for vocal recordings with presence EQ for clarity.

You: "Process this vocal recording"
→ DC offset → HPF 100Hz → noise reduction 10dB → compression 3:1 → presence EQ (+3dB treble, -1dB bass) → safe loudness check

auto_cleanup_live — Live / field / noisy recording

Aggressive cleanup for noisy environments. First 0.5s must be ambient noise for profiling.

You: "This is a noisy live recording, clean it up"
→ DC offset → HPF 100Hz → click removal → noise reduction 18dB → compression 5:1 → safe loudness check

auto_master_music — Music mastering

Genre-tuned mastering with 6 presets: edm, hiphop, rock, pop, classical, acoustic.

You: "Master this hip-hop track"
→ HPF 30Hz → click removal → compression 2:1 → bass +3dB treble +1dB → safe loudness check

You: "Master this for a classical album"
→ HPF 30Hz → click removal → compression 1.3:1 (very gentle) → no EQ → safe loudness check

auto_lofi_effect — Creative lo-fi / vintage

Apply a warm, vintage lo-fi sound. Presets: light, medium, heavy.

You: "Give this a lo-fi vibe"
→ HPF → LPF (muffled highs) → bass/treble warmth → compression 2:1 → safe loudness check

After a Pipeline: Adjusting Loudness

Pipelines intentionally leave loudness alone (they only reduce if peaks are clipping). To hit a streaming target:

You: "Now normalize this to -14 LUFS for Spotify"
→ AI uses loudness_normalize tool with lufs_level=-14

You: "Normalize to -16 LUFS for podcast"
→ AI uses loudness_normalize tool with lufs_level=-16

Why not do this automatically? LUFS normalization can boost quiet/badly recorded audio by 10-20 dB, which blows it out. By separating cleanup from loudness, you get to check the results before the final loudness step.

Local Transcription (Experimental)

This feature is experimental and requires separate setup. Everything else works without it.

Powered by faster-whisper — runs entirely offline, your audio never leaves your machine:

• 5 model sizes: tiny, base, small, medium, large-v3
• Transcribe full audio or just a selection
• Export as SRT, VTT, or plain text subtitles
• Auto-add Audacity labels at each spoken segment
• Language detection or specify 99+ languages

Setup required before first use: See Transcription Setup for installation steps.

What's New - v0.3.0

The server ships as a Claude Code plugin, alongside the existing pip/installer paths.

• Claude Code plugin: install with /plugin install audacity@robworks-claude-code-plugins, no pip step and nothing to add to your MCP client config - the launcher resolves uv itself and runs the server straight from the plugin's own checkout (macOS and Linux; Windows still uses install.bat)
• New commands: /audacity:setup walks through uv, mod-script-pipe, and a real round-trip check; /audacity:doctor diagnoses a failing connection across both the plugin side and the server side
• Transcription is now optional: faster-whisper (and the ctranslate2/onnxruntime it pulls in) moved out of the base install into a transcription extra - pip install "audacity-mcp-max[transcription]", or /audacity:setup --transcription from the plugin. The 7 transcription tools still register either way; calling one without the extra installed raises a clean error naming the fix
• Bug fix: install.sh enabled mod-script-pipe without checking whether Audacity was running - Audacity rewrites its config on quit, so the change was silently reverted the next time the user closed the app, after the installer had already reported success. It now refuses to write while Audacity is running and says why

Troubleshooting

Start Here: audacity_health_check

Ask your assistant to run audacity_health_check before debugging anything else.It reports whether each script pipe exists, how old the pipe files are (theyoutlive Audacity, so their presence alone proves nothing), whether Audacityactually answers a round trip, which copy of the client is installed, and thedefault project sample rate — with the specific next step for whatever it finds.

mod-script-pipe Not Enabled

The installer enables this automatically, but if it didn't work (e.g. Audacity was never opened before), enable it manually:

1. Open Audacity
2. Go to Edit → Preferences (Windows/Linux) or Audacity → Preferences (macOS)
3. Click Modules in the left sidebar
4. Set mod-script-pipe to Enabled
5. Click OK and restart Audacity

Connection Issues

Pipeline Issues

Audio Quality Tips

General Issues

Architecture

┌──────────────┐     stdio      ┌──────────────┐   named pipe   ┌──────────────┐
│  MCP Client  │◄──────────────►│ audacity-mcp-max  │◄──────────────►│   Audacity   │
│(AI assistant)│    (JSON-RPC)  │   FastMCP    │  (commands)    │              │
└──────────────┘                └──────────────┘                └──────────────┘
                                       │
                                       ├── audacity_mcp/main.py          (entry point)
                                       ├── audacity_mcp/audacity_client.py (pipe I/O)
                                       ├── audacity_mcp/tool_registry.py  (auto-loader)
                                       └── audacity_mcp/tools/            (11 modules)

Key Design Decisions

• Named pipes, not TCP — Direct IPC to Audacity's mod-script-pipe. No network exposure, no port conflicts.
• Zero exec/eval — Every operation maps to a static handler with input validation. No arbitrary code execution.
• Cross-platform — Windows uses Win32 API via ctypes, Unix uses standard file I/O.
• Async throughout — All tool handlers are async. Blocking pipe I/O runs in an executor pool with configurable timeouts.
• Safe pipelines — Pipelines measure audio before making loudness decisions. They only reduce, never boost.
• Dynamic tool registration — Drop a module in audacity_mcp/tools/, export a register(mcp) function, and it's automatically discovered.

Project Structure

audacity-mcp-max/
├── audacity_mcp/
│   ├── main.py                 # FastMCP server entry point
│   ├── audacity_client.py      # Cross-platform named pipe client
│   ├── tool_registry.py        # Auto-discovers and registers tool modules
│   └── tools/
│       ├── analysis_tools.py   # Audio analysis (contrast, spectrum, beats)
│       ├── cleanup_tools.py    # Noise reduction, mastering, 9 pipelines
│       ├── edit_tools.py       # Cut, copy, paste, split, join, trim
│       ├── effects_tools.py    # Reverb, echo, pitch, EQ, filters
│       ├── generate_tools.py   # Tone, noise, chirp, DTMF generation
│       ├── label_tools.py      # Label management
│       ├── project_tools.py    # Project/file operations
│       ├── selection_tools.py  # Selection and cursor control
│       ├── track_tools.py      # Track management
│       ├── transcription_tools.py  # Whisper-based transcription
│       └── transport_tools.py  # Playback and recording control
├── audacity_mcp_shared/
│   ├── constants.py            # Pipe paths, timeouts, allowed formats
│   ├── error_codes.py          # Typed error codes (pipe/command/validation)
│   └── pipe_protocol.py        # Command formatting and response parsing
├── tests/                      # 60 tests
├── docs/
│   ├── INSTALLATION.md         # Detailed setup guide
│   └── TOOLS.md                # Complete tool reference
└── pyproject.toml

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -x -q

Adding New Tools

1. Create a module in audacity_mcp/tools/ (or add to an existing one)
2. Export a register(mcp: FastMCP) function
3. Define your tools with @mcp.tool() decorators
4. That's it — the tool registry auto-discovers it on startup

# audacity_mcp/tools/my_tools.py
from mcp.server.fastmcp import FastMCP
from audacity_mcp_shared.error_codes import AudacityMCPError, ErrorCode


def register(mcp: FastMCP):
    from audacity_mcp.main import client

    @mcp.tool()
    async def my_custom_effect(intensity: float = 0.5) -> dict:
        """Apply my custom effect to the selected audio."""
        if not 0 <= intensity <= 1:
            raise AudacityMCPError(ErrorCode.VALUE_OUT_OF_RANGE, "intensity must be 0-1")
        return await client.execute_long("MyEffect", Intensity=intensity)

See CONTRIBUTING.md for full guidelines.

Support

If audacity-mcp-max has saved you time or helped with your audio projects, consider buying me a coffee:

Your support helps keep this project maintained and free for everyone.

Documentation

• Installation Guide — Detailed setup for Windows, macOS, Linux
• Tool Reference — Complete reference for all 132 tools with parameters and ranges
• Contributing — How to add tools and contribute
• Changelog — Version history and release notes

License

Apache License 2.0 — see LICENSE for details.

Built by Daniel Hodgetts • 𝕏 @daehonz1