audaMcp

An MCP (Model Context Protocol) server that gives LLMs professional audio editing capabilities: stems separation, neural dereverb/de-echo, repair (declick/declip/decrackle), intelligent silence removal, mastering, and an optional Audacity 3.x bridge.

Runs locally — no cloud, no API keys for the audio processing itself.

What it does

All tools take local file paths in, write a new file out, and return JSON with metrics_before / metrics_after so the LLM can verify the change landed. Audio never goes over the wire.

Quick start

CLI install (terminal use)

:: Windows
pip install audamcp          # core DSP only (~10 MB)
pip install audamcp[ml]      # + Demucs stem separation (~1.3 GB)

# macOS / Linux
pip install audamcp
pip install audamcp[ml]

MCP server install (for LLM clients)

:: Windows
cd audamcp
scripts\install.bat --cuda      :: GPU (RTX 3050 etc.) — recommended
:: or
scripts\install.bat             :: CPU only
:: or
scripts\install.bat --no-ml     :: skip Demucs/dereverb entirely

scripts\register_clients.py     :: register with all installed clients
python scripts\smoke_test.py    :: verify

# macOS / Linux
cd audamcp
./scripts/install.sh --cuda     # or omit flag for CPU
python scripts/register_clients.py
python scripts/smoke_test.py

Then restart your LLM client and call auda_health to confirm.

Supported LLM clients

register_clients.py auto-detects and configures:

• Claude Code — claude mcp add
• Claude Desktop — writes claude_desktop_config.json
• Cursor — writes .cursor/mcp.json
• GLM / ZCode — writes configs/glm_zcode.json + prints the snippet
• Codex / other MCP — codex mcp add + configs/codex.toml

The server speaks stdio MCP, so any MCP-aware client works.

GPU / memory policy

• Defaults to auto-detect: uses CUDA if free VRAM ≥ ~1 GB, else CPU.
• Per-call device="cpu" / "cuda" override on every ML tool.
• Long files on small GPUs (RTX 3050 / 4GB) auto-segment via Demucs's native --segment flag — no OOM crashes. See audamcp/config.py.
• CUDA OOM during Demucs triggers an automatic CPU retry.

Audacity bridge

The auda_audacity_* tools require Audacity 3.x with mod-script-pipe enabled. See scripts/enable_audacity_pipe.md.

Audacity 4.0 removed mod-script-pipe; the bridge is 3.x-only. All other tools work regardless of Audacity version (or with no Audacity installed).

Skill

Install dpf-audio-pro (the companion skill) into your skills directory to give the LLM curated workflows that chain these tools: podcast cleanup, music mastering, vocal isolation, dialog restoration, and archival restoration. See the skill's SKILL.md.

CLI usage

The auda command gives terminal access to all DSP functions directly:

# Analyze a file
auda analyze track.wav

# Peak normalize to -1 dBFS
auda normalize track.wav -o normalized.wav --target-db -1

# LUFS normalize to Spotify target
auda normalize track.wav -o spotify.wav --method lufs --lufs-target spotify

# Trim 10s–30s
auda trim track.wav -o clip.wav --start 10 --end 30

# Fade in 2s, fade out 3s
auda fade track.wav -o faded.wav --fade-in 2 --fade-out 3

# Concatenate with 0.5s gap
auda concat intro.wav body.wav outro.wav -o full.wav --gap 0.5

# Mix two files at different gains
auda mix music.wav vocals.wav -o mixed.wav --gains 0.7,1.0

# Transcode to 48kHz mono MP3
auda convert track.wav output.mp3 --sample-rate 48000 --channels 1 --bitrate 192k

# Apply EQ
auda eq track.wav -o eq.wav --highpass 30 --low-shelf-db 2 --high-shelf-db -1

# Compress
auda compressor track.wav -o comp.wav --threshold -18 --ratio 3 --attack 15 --release 180

# Limit
auda limiter track.wav -o limited.wav --ceiling -1

# Full mastering chain
auda master track.wav -o mastered.wav --target spotify

# Stem separation (requires demucs: pip install audamcp[ml])
auda stems track.wav -o stems_dir/
auda vocals track.wav -o vocals.wav
auda karaoke track.wav -o backing.wav

# Denoise
auda denoise noisy.wav -o clean.wav --algorithm spectral --strength 0.85

# Check system
auda health

# Raw ffprobe metadata
auda probe track.wav

All commands output JSON by default with {ok, tool, output, processing_seconds, ...}.

Project layout

audamcp/
├── pyproject.toml          # uv-managed; deps split into core / ml / ml-dfn
├── audamcp/
│   ├── server.py           # FastMCP app + @mcp.tool registrations
│   ├── cli.py              # `auda` CLI (click) — direct terminal access
│   ├── audio_io.py         # load / save / convert / probe
│   ├── loudness.py         # BS.1770 + streaming target table
│   ├── analyze.py          # BPM, spectral, dynamic range
│   ├── master.py           # pedalboard mastering chain + dynamics
│   ├── dsp_util.py         # convert / trim / fade / concat / mix / speed
│   ├── desilence.py        # silence detect / trim / remove / split
│   ├── repair.py           # declick / declip / decrackle
│   ├── denoise.py          # noisereduce + DeepFilterNet
│   ├── stems.py            # Demucs (htdemucs / _ft / _6s)
│   ├── dereverb.py         # bs_roformer dereverb / deecho
│   ├── audacity_bridge.py  # mod-script-pipe named-pipe client
│   ├── config.py           # device detection + paths
│   └── utils.py            # timing + JSON envelopes
├── scripts/                # install / register / smoke_test
└── configs/                # ready-to-paste per-client snippets

License

MIT.