使用说明

Audacity MCP服务器

MCP（模型上下文协议）服务器，用于通过以下方式控制Audacity mod-script-pipe。专为无需手动LLM驱动的音频管道而设计——Claude Code（或任何MCP客户端）可以完全通过工具调用生成、处理和导出音频，而不需要手动Audacity交互。

特性

通过以下方式连接到Audacity mod-script-pipe
线程安全——所有管道I/O都通过锁序列化，并通过以下方式在事件循环中运行 asyncio.to_thread，因此快速连续的工具调用永远不会交错
生成器工具在空项目上工作——如果不存在轨道，服务器会向其中写入一个无声的WAV /tmp，导入它，并将其用作生成目标（Audacity的 Duration 脚本参数被默默忽略；需要选择）
全参数化工具 Export2, Import2, Select, GetInfo, SetTrackStatus, SetTrackAudio, OpenProject2, SaveProject2
复合物 generate_and_export 处理整个生成的工具→ 选择→ 出口→ 一次通话中的清理周期
自动检测中的管道路径后缀 /tmp （例如。 .501)
用途 stdio 传输（与克劳德代码、克劳德桌面、Codex兼容）

需求

大胆3.x+
Python 3.10+
mod-script-pipe 在Audacity中启用（见下文）

安装

git clone https://github.com/DaRealDaHoodie/mcp-audacity.git
cd mcp-audacity
./scripts/setup.sh

手动设置：

python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install "mcp[cli]>=1.6.0" "httpx>=0.28.1"

在Audacity中启用mod脚本管道

打开Audacity。
首选模块偏好：
- macOS: Audacity → Settings → Modules
- Windows/Linux: Edit → Preferences → Modules
集 mod-script-pipe 从 New 或 Disabled 到 Enabled.
重新启动Audacity。

验证管道是否存在：

ls -l /tmp/audacity_script_pipe.to.* /tmp/audacity_script_pipe.from.*

如果两个文件都出现，则Audacity已准备就绪。

快速烟雾测试

# Audacity must already be running with mod-script-pipe enabled
./scripts/smoke_test.sh

运行服务器

./scripts/run.sh

预期启动日志：

Audacity MCP server starting up
Opened Audacity mod-script-pipe
Connected to Audacity mod-script-pipe

从克劳德代码连接

添加到MCP配置中（例如。 ~/.claude/claude_desktop_config.json 或通过 claude mcp add):

{
  "mcpServers": {
    "audacity": {
      "command": "/absolute/path/to/mcp-audacity/.venv/bin/python",
      "args": ["/absolute/path/to/mcp-audacity/audacity_mcp_server.py"]
    }
  }
}

从Codex连接

codex mcp add AudacityMCP -- /absolute/path/to/mcp-audacity/.venv/bin/python /absolute/path/to/mcp-audacity/audacity_mcp_server.py

工具参考

发电机工具

所有发电机都在空项目上工作。如果不存在曲目，服务器会自动创建正确曲目的无声曲目 duration 在 /tmp，导入它，并针对它运行生成器（生成器取代了静默）。如果轨迹已经存在，生成器将像往常一样应用于当前选择。

为什么要采取变通办法？ Audacity的脚本API静默地忽略 Duration 参数——生成器总是需要一个带有选择的现有轨道。服务器透明地处理这个问题，所以你永远不必考虑它。

工具	关键参数	注意事项
`cmd_Noise`	`duration`, `noise_type` （白色/粉红色/布朗色）， `amplitude`
`cmd_Tone`	`duration`, `frequency`, `amplitude`, `waveform` （正弦/方形/锯齿形）
`cmd_Chirp`	`duration`, `start_frequency`, `end_frequency`, `start_amplitude`, `end_amplitude`, `waveform`, `interpolation`	频率扫描
`cmd_Pluck`	`duration`, `pitch` （MIDI音符编号）， `fade` （突然/逐渐）
`cmd_DtmfTones`	`sequence`, `duration`, `amplitude`	手机键盘铃声
`cmd_RhythmTrack`	`tempo`, `beats_per_bar`, `duration`	点击轨迹
`cmd_RissetDrum`	`duration`, `frequency`, `decay`, `cf`, `bw`, `noise`, `gain`
`cmd_Nyquist`	`command`	完整的Nyquist/Lisp DSP表达式根据选择运行，例如。 `(scale 0.5 s)`

效果工具

以下所有效果均已完全参数化，无需打开任何对话框即可应用。

工具	关键参数	注意事项
`cmd_Amplify`	`ratio`, `allow_clipping`	`ratio=0.5` → -6 dB, `ratio=2.0` → +6 dB
`cmd_LoudnessNormalization`	`normalize_to` （LUFS/RMS）， `lufs_level`, `rms_level`, `dual_mono`	`-23.0` LUFS=广播， `-14.0` LUFS=流媒体
`cmd_Normalize`	`peak_level` （dBFS）， `apply_volume`, `remove_dc_offset`, `stereo_independent`	峰值归一化——不同于LUFS响度
`cmd_Compressor`	`threshold`, `noise_floor`, `ratio`, `attack_time`, `release_time`, `normalize`, `use_peak`	内部使用Audacity的LegacyCompressor
`cmd_Limiter`	`threshold_db`, `makeup_target_db`, `knee_width_db`, `lookahead_ms`, `release_ms`	硬天花板；压缩后使用
`cmd_Reverb`	`room_size`, `reverberance`, `hf_damping`, `wet_gain`, `dry_gain`, `stereo_width`, `wet_only`	除增益（dB）外的所有值0-100
`cmd_Echo`	`delay` （秒）， `decay` （0.0–1.0）	简单回声/重复效果
`cmd_Repeat`	`count`	重复选择；总播放次数=计数+1
`cmd_ChangePitch`	`percentage`, `use_high_quality`	百分比偏移，例如50.0≈一个八度音阶向上
`cmd_ChangeSpeed`	`percent`	同时改变速度和音高
`cmd_ChangeTempo`	`percent`, `use_high_quality`	在不影响音高的情况下改变节奏
`cmd_TruncateSilence`	`threshold` （dBFS）， `action`, `minimum`, `truncate`, `compress`	动作： `"Truncate Detected Silence"` 或 `"Compress Excess Silence"`
`cmd_Paulstretch`	`stretch_factor`, `time_resolution`	极端时间拉伸； `stretch_factor=10.0` =10倍长
`cmd_BassAndTreble`	`bass` （dB）， `treble` （dB）， `gain` （dB）， `link_sliders`	EQ调节，±30dB范围
`cmd_ClickRemoval`	`threshold` (0–900), `max_spike_width` （0–40个样本）	删除点击和弹出
`cmd_NoiseReduction`	（无参数）	使用上次捕获的配置文件应用——请参阅下面的注释
`cmd_NoiseGate`	`threshold`, `mode`, `stereo_link`, `level_reduction`, `attack`, `hold`, `decay`	闸门或分析模式
`cmd_HighPassFilter`	`frequency` （Hz）， `rolloff` （dB6-dB48）	低于频率
`cmd_LowPassFilter`	`frequency` （Hz）， `rolloff` （dB6-dB48）	频率以上的削减
`cmd_NotchFilter`	`frequency` （Hz）， `q`	删除特定频率；较高的Q=较窄的凹口
`cmd_AdjustableFade`	`fade_type` （向上/向下/S曲线向上/S曲线向下）， `curve`, `units`, `gain0`, `gain1`	比普通淡入淡出更具控制性
`cmd_Tremolo`	`wave`, `phase`, `wet`, `lfo`	调幅；lfo（赫兹）
`cmd_StereoToMono`	（无参数）	将立体声曲目转换为单声道

没有有意义的自动化参数（淡入、淡出、反转、反转、修复等）的剩余效果可用作无参数工具——它们适用于Audacity的默认值。

`cmd_NoiseReduction` --需要手动配置文件

Audacity的脚本API公开 没有参数 用于降噪。两遍轮廓捕获无法自动化。工作流程：

在Audacity中，选择仅包含背景噪波的区域
Effects → Noise Reduction → Get Noise Profile
选择要清理的音频
呼叫 cmd_NoiseReduction --它应用上次捕获的配置文件

要实现全自动噪音清理，请使用 cmd_NoiseGate 相反（完全参数化，没有手动步骤）。

宏工具

工具	关键参数	注意事项
`cmd_ApplyMacro`	`name`	按确切名称运行已保存的Audacity宏。使用Audacity中的宏管理器创建链接任何效果序列的宏。

宏是处理复杂可重复管道的最强大工具——在Audacity中构建一条链，然后用一个 cmd_ApplyMacro 电话。

文件工具

工具	关键参数	注意事项
`cmd_Import2`	`filename` （绝对路径）	将音频作为新曲目导入
`cmd_Export2`	`filename`, `num_channels`	从扩展名推断的格式： `.wav` `.ogg` `.mp3` `.flac` `.aiff`
`cmd_OpenProject2`	`filename`, `add_to_history`	打开 `.aup3` 项目
`cmd_SaveProject2`	`filename`, `add_to_history`	保存 `.aup3` 项目

选择和跟踪工具

工具	关键参数	注意事项
`cmd_Select`	`start`, `end` （秒）， `track` （基于0）， `track_count`, `mode` （设置/添加/删除）	组合时间+曲目选择
`cmd_SelectTime`	`start`, `end`, `relative_to`	仅限时间选择；relative_to:项目开始/项目结束/选择开始等。
`cmd_SelectTracks`	`track` （基于0）， `track_count`, `mode`	仅跟踪选择
`cmd_GetInfo`	`info_type` （曲目/剪辑/标签/信封/盒子/命令/首选项/选择）， `format`	检查项目状态。使用 `Type=Selection` 读取当前选择。
`cmd_SetTrackStatus`	`track` （基于0）， `name`, `selected`	重命名或选择/取消选择曲目
`cmd_SetTrackAudio`	`track` （基于0）， `mute`, `solo`, `volume` （dB）， `pan` （-1..1）	设置混合属性
`cmd_SetLabel`	`label` （基于0的指数）， `text`, `start`, `end`	编辑现有标签的文本或时间范围
`cmd_SetClip`	`track`, `at` （当前开始）， `color` （颜色0–颜色3）， `start` （新开始）	移动剪辑或重新着色剪辑
`cmd_SetEnvelope`	`track`, `time`, `value` (0.0–2.0), `delete`	添加、移动或删除体积包络点
`cmd_BeatFinder`	`threshold` （0–100）	检测节拍并添加标签
`cmd_LabelSounds`	`threshold`, `measurement`, `silence_duration`, `sound_duration`, `label_type`, `text`	通过声音/静音检测自动标记
`cmd_StereoToMono`	（无参数）	将立体声转换为单声道

首选工具

工具	关键参数	注意事项
`cmd_GetPreference`	`name` （关键路径）	读取任何Audacity首选项，例如。 `Quality/DefaultProjectSampleRate`
`cmd_SetPreference`	`name`, `value`, `reload`	写下任何Audacity偏好。 `reload=True` 立即适用。

管道的常见首选项键：

关键	它控制什么
`Quality/DefaultProjectSampleRate`	新项目的默认采样率（例如。 `"44100"`, `"48000"`)
`Quality/DefaultProjectSampleFormat`	钻头深度： `"float"`, `"int24"`, `"int16"`
`AudioIO/PlaybackDevice`	播放设备名称

复合工作流工具

`cmd_generate_and_export`

在一次调用中处理整个生成和导出周期。适用于批处理管道，您希望在不编排单个步骤的情况下生成许多音频文件。

generator:    Noise | Tone | Chirp | Pluck
duration:     seconds (float)
output_path:  absolute path including filename and extension
              format is inferred from extension: .wav .ogg .flac .aiff
amplitude:    0.0–1.0
frequency:    Hz (for Tone/Chirp/Pluck)
noise_type:   White | Pink | Brownian (Noise only)
waveform:     Sine | Square | Sawtooth (Tone/Chirp only)
num_channels: 1 (mono) or 2 (stereo)

内部运行：generate→ 全选→ 出口2→ TrackClose。因为每次通话只创建一个音轨 TrackClose: 将项目留空，为下一次迭代做好准备，而无需在每次调用时打开新的Audacity窗口。

示例提示克劳德：

生成5个WAV文件：白噪声2s、440Hz正弦1s、880Hz锯齿1s、粉红噪声3s和一个拔出的A4 1s。将它们保存到~/sounds/作为noise_white.WAV、tone_440.WAV、tone_880_saw.WAV、noise_pink.WAV、plug_A4.WAV

管线架构

运作原理

Claude Code
    │
    ▼  MCP tool calls (stdio)
audacity_mcp_server.py
    │
    ▼  named pipe (mod-script-pipe)
Audacity 3.x
    │
    ▼  file output
/your/output/directory/

重要约束条件

一个管道，一个流程。 Audacity的mod脚本管道创建了一对FIFO。MCP服务器打开它们并在其生命周期内保存它们。服务器运行时，如果独立脚本也尝试读取，则其他进程不应打开相同的管道 pipe_from，响应将在两个读取器之间分配，两者都将得到损坏的输出。所有Audacity交互都应该通过此服务器。

命令是顺序的。 线程锁意味着每次工具调用都会等待 BatchCommand finished 在发送下一个命令之前。这对于快速顺序调用是安全的，但意味着Audacity端没有设计上的并行性。

大胆一定在奔跑。 服务器不启动Audacity。在启动服务器之前，启用mod脚本管道启动Audacity。

何时使用Audacity与Python+ffmpeg

对于纯音频合成和格式转换，Python wave 模块+ ffmpeg 更简单，没有管道约束。当您特别需要Audacity时，请使用此服务器：

需要	使用
合成音调、噪音、扫频	要么——通过此服务器或Python+ffmpeg进行Audacity
批量OGG/MP3导出+响度归一化	ffmpeg(`loudnorm` 过滤器）更容易
降噪、消除点击/裂纹	Audacity——更强的算法
奈奎斯特脚本	仅限Audacity
加载现有 `.aup3` 项目和处理	仅限Audacity
LLM驱动的批量生成许多文件	`cmd_generate_and_export` 复合工具，或Python+ffmpeg

故障排除

症状	修复
`Failed to open Audacity pipes`	确认Audacity在启用mod脚本管道的情况下运行；检查 `/tmp/audacity_script_pipe.*` 存在
`spawn uv ENOENT`	在MCP配置中使用绝对路径
`"Noise" requires one or more tracks to be selected`	MCP工具不应该出现这种情况——它们会在空项目上自动引导一个静默轨道。如果您看到此消息，请确认您正在拨打电话 `cmd_Noise` （不是生的 `Noise:` 裸命令），并且服务器在最新更改后重新启动。
`ApplyMacro` 不执行任何操作或出现错误	宏名称必须与Audacity的宏管理器中显示的完全匹配（区分大小写）。调用前验证宏是否存在 `cmd_ApplyMacro`.
Nyquist命令错误	表达式必须是有效的Nyquist/Lisp。这 `s` 变量是指当前选择。首先在Audacity的Nyquist Prompt中进行测试。
命令超时或返回空	另一个进程正在读取 `pipe_from`。停止它并重新启动MCP服务器。
工具在调用之间的行为不一致	确保您使用的是最新版本；它通过锁对所有命令进行序列化，并读取直到 `BatchCommand finished`

许可证

麻省理工学院