AudacityMCP

AudacityMCP 将任何兼容 MCP 的 AI 助手连接到 Audacity，通过涵盖效果、清理、母带处理、转写等领域的 144 个工具，赋予其对音频编辑的完全控制。对你的 AI 助手说出需求，它就会实时编辑你的音频。

无需云端。音频处理不需要任何 API 密钥。一切通过 Audacity 的命名管道接口在本地运行。

如果这个项目对你有用，点一个 star 就能帮助更多人发现它——这就是这个项目的全部推广预算。想帮助维护它？点击顶部的 Sponsor 徽章。

兼容性： AudacityMCP 目前仅支持 Audacity 3.x。尚不支持 Audacity 4.x——我们希望未来能增加支持。

适用客户端

AudacityMCP 适用于任何支持 Model Context Protocol 的 AI 客户端：

• Claude Desktop — Anthropic 的桌面应用

• Claude Code — CLI 代理

• Cursor — 支持 MCP 的 AI 代码编辑器

• 任何其他兼容 MCP 的客户端

快速开始

1. 获取 AudacityMCP

方式 A： 点击上方绿色 Code 按钮 → Download ZIP → 解压到文件夹

方式 B： 使用 git 克隆：

git clone https://github.com/xDarkzx/Audacity-MCP.git

2. 运行安装程序（自动完成其余所有设置）

Windows： 在文件资源管理器中双击 install.bat，或者——如果你已经在上面 git clone 步骤的终端里——直接在同一个 PowerShell/命令提示符窗口中继续：

cd Audacity-MCP
.\install.bat

macOS / Linux：

cd Audacity-MCP
bash install.sh

安装程序会做 3 件事：从这个本地文件夹（就是你刚下载/克隆的那个——不涉及 PyPI 或 GitHub 拉取）安装 audacity-mcp，在 Audacity 中启用 mod-script-pipe，并配置 Claude Desktop——无需手动编辑 JSON。在修改任一配置文件之前，它会先请求确认，先说明它将要做什么，并且在修改前始终备份现有文件。想在不做任何更改的情况下查看它将执行的所有操作？加上 --dry-run：.\install.bat --dry-run / bash install.sh --dry-run。

注意：install.bat/install.sh 必须在此文件夹内运行——它们只安装旁边的代码，本身不会下载任何内容。

如果你不使用 Claude Desktop，请通过 pip install audacity-mcp-server 手动安装，并添加到客户端的 MCP 配置中：

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

有关配置文件位置，请查阅你所用客户端的 MCP 文档。

客户端找不到/无法运行 audacity-mcp？ GUI 应用不一定能看到终端看到的同一个 PATH。运行 python -c "import sysconfig; print(sysconfig.get_path('scripts'))"，使用它输出的完整路径（Windows 上加 \audacity-mcp.exe，macOS/Linux 上加 /audacity-mcp）作为 "command"，而不是裸命令名。

不需要 install.bat/install.sh，没有任何东西会自动改动你的系统——三步，全部手动完成：

1. 在 Audacity 中启用 mod-script-pipe：编辑 → 偏好设置（Windows/Linux）或 Audacity → 偏好设置（macOS）→ 模块 → 将 mod-script-pipe 设为已启用 → 确定 → 重启 Audacity。

2. 安装软件包：打开终端（Windows 上用命令提示符/PowerShell，macOS/Linux 上用终端）并运行 pip install audacity-mcp-server——普通的 PyPI 安装，无需克隆仓库。

3. 配置 Claude Desktop：打开 Claude Desktop → 设置（齿轮图标）→ 开发者选项卡 → 编辑配置——这会在文本编辑器中打开 claude_desktop_config.json。在 "mcpServers" 块内添加以下内容，保留你已有的其他服务器：

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

   保存文件并完全重启 Claude Desktop（从系统托盘退出，而不仅仅是关闭窗口）。

这就是完整的安装过程——更多细节和按操作系统的说明，请参阅安装指南。

重启后 "audacity" 没有显示为工具？ 上面的 "command": "audacity-mcp" 只有在该命令位于 Claude Desktop 自身使用的 PATH 上时才有效，但情况并非总是如此（尤其是如果安装 Python 时 Claude Desktop 已经打开）。如果无法连接，请在终端中运行以下命令找到真实安装位置：python -c "import sysconfig; print(sysconfig.get_path('scripts'))"——然后用它输出的完整路径加上 \audacity-mcp.exe（Windows，记得每个反斜杠都要写成两个：\\）或 /audacity-mcp（macOS/Linux）替换上面的 "audacity-mcp"。

3. 开始编辑

打开 Audacity，加载一些音频，然后对你的 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。 AudacityMCP 通过 Audacity 的命名管道通信——它无法替你启动 Audacity。

有关所有平台和 MCP 客户端的详细设置，请参阅完整的安装指南。

Related MCP server: ReaperMCP

为什么选择 AudacityMCP？

没有 AudacityMCP： 你需要手动浏览菜单、凭耳朵调整效果参数、逐个应用效果、查阅 ACX 规范，然后反复尝试直到听起来满意。

有了 AudacityMCP： 你用自然语言描述需求，AI 处理其余一切——选择合适的效果、设置行业标准参数、串联多个操作。

AudacityMCP 尤其适合：

• 播客创作者：希望获得一致、专业的声音，但不需要音频工程知识

• 音乐人：需要按曲风快速完成母带处理

• 内容创作者：处理访谈、配音或现场录音

• 任何人：与其翻菜单，不如直接描述想要的效果

它能做什么？

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

功能特性

11 个类别共 144 个工具

流水线

AudacityMCP 内置 9 个一键流水线，覆盖常见音频任务。每个流水线都针对录音质量较差的音频做了安全设计——绝不会危险地提升你的音频。流水线会清理并改善你的音频，之后如有需要，你可以手动调整响度。

管道如何工作

1. 你告诉 AI 你想要什么（例如“清理这个播客”）

2. AI 选择合适的管道并启动它

3. 管道在后台运行——你会得到一个 job_id 返回

4. 每 15-30 秒使用 check_pipeline_status 轮询以监控进度

5. 完成后，Audacity 中会弹出提示

安全规则： 管道只会降低过高的峰值。它们绝不会提升响度。如果你想达到特定的 LUFS 目标（例如 Spotify 的 -14），请在检查结果满意后让 AI 运行 loudness_normalize。

管道参考

auto_analyze_audio — 处理前分析

测量你的音频并推荐最佳管道。如果不确定该怎么做，请先运行此命令。

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

auto_cleanup_audio — 仅安全清理

清理噪声和伪影，完全不改变响度。当电平已经合适时使用。

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

auto_cleanup_podcast — 播客 / 配音

针对口语的专业广播处理。

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

auto_audiobook_mastering — 有声书（ACX/Audible）

针对有声书分发满足 ACX 要求。

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 — 访谈 / 对话

轻触处理对话——保留自然动态。

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

auto_cleanup_vocal — 歌唱 / 录音室人声

针对人声录音调校，带有清晰度增强 EQ。

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 — 现场 / 外景 / 嘈杂录音

针对嘈杂环境的强力清理。前 0.5 秒必须是环境噪声用于分析。

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 — 音乐母带

针对不同风格调校的母带处理，有 6 种预设：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 — 创意 lo-fi / 复古

应用温暖、复古的 lo-fi 声音。预设：light、medium、heavy。

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

管道之后：调整响度

管道有意保持响度不变（仅在峰值削波时降低）。要达到流媒体目标：

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

为什么不自动执行？ LUFS 归一化可能会将安静或录制不佳的音频提升 10-20 dB，从而使其失真。通过将清理与响度分离，你可以在最终响度步骤之前检查结果。

本地转录（实验性）

此功能为实验性，需要单独设置。其他所有功能无需它即可正常工作。

由 faster-whisper 提供支持——完全离线运行，你的音频绝不会离开你的机器：

• 5 种模型大小：tiny、base、small、medium、large-v3

• 转录完整音频或仅转录选区

• 导出为 SRT、VTT 或纯文本字幕

• 在每个语音片段自动添加 Audacity 标签

• 语言检测或指定 99+ 种语言

首次使用前需要设置： 安装步骤请参阅 转录设置。

想要 GPU 加速（快 10-20 倍）？ 运行 audacity-mcp-setup-gpu——或者下载 setup_gpu.bat/setup_gpu.sh 并双击/运行它，如果你不想使用终端的话。它会检测你的 GPU，安装所需内容，并验证其确实有效。仅限 NVIDIA GPU（AMD/Intel 显卡和 macOS 完全不受转录后端支持——任何 NVIDIA 显卡都可以，GeForce 不是必需，只要拥有 NVIDIA GPU 即可）。没有 NVIDIA GPU？CPU 也能正常工作，只是在长文件上较慢。

脚本说成功了但转录仍然慢/在 CPU 上？那意味着 Claude Desktop 从不同的 Python 启动 audacity-mcp，而不是脚本验证的那个——请参阅 修复方法（手动配置编辑，五分钟）。

新增内容 — v0.1.3

32 个新工具（99 → 131），管道调优修复，并已针对 Audacity 进行实时测试。

• 新效果：Reverse、Invert、Repair、AutoDuck、NotchFilter、VocalReduction、AdjustableFade、StudioFadeOut、CrossfadeClips、CrossfadeTracks、ClipFix、SlidingStretch、Tremolo

• 新编辑：Split（就地）、SplitCut、SplitDelete、Disjoin + 将旧 split 重命名为 edit_split_new

• 新轨道：StereoToMono、MixAndRenderToNew、MuteAll、UnmuteAll、Resample、AlignEndToEnd、AddLabelTrack

• 新选区：CursorToTrackStart/End、CursorToProjectStart/End、SelectCursorToTrackEnd

• 新项目：EditMetadata、ImportMIDI

• 新标签：RegularIntervalLabels

• 管道修复：ACX 峰值上限 -3.0→-3.5dB，现场降噪 18→12dB，播客压缩 10ms/1s→30ms/200ms，访谈释放 1s→200ms

• 错误修复：effect_repair 现在使用长超时（Audacity 在无效选区时显示弹出窗口）

• 验证：为 AutoDuck、VocalReduction、SlidingStretch、Resample 添加了缺失的范围检查

故障排除

mod-script-pipe 未启用

安装程序会自动启用此功能，但如果未生效（例如 Audacity 从未打开过），请手动启用：

1. 打开 Audacity

2. 转到 编辑 → 首选项（Windows/Linux）或 Audacity → 首选项（macOS）

3. 点击左侧边栏中的 模块

4. 将 mod-script-pipe 设置为 已启用

5. 点击 确定 并 重启 Audacity

连接问题

管道问题

音频质量提示

一般问题

架构

┌──────────────┐     stdio      ┌──────────────┐   named pipe   ┌──────────────┐
│  MCP Client  │◄──────────────►│ AudacityMCP  │◄──────────────►│   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)

关键设计决策

• 命名管道而非 TCP —— 直接与 Audacity 的 mod-script-pipe 进行 IPC。无网络暴露，无端口冲突。

• 零 exec/eval —— 每个操作都映射到带输入验证的静态处理器。无任意代码执行。

• 跨平台 —— Windows 通过 ctypes 使用 Win32 API，Unix 使用标准文件 I/O。

• 全程异步 —— 所有工具处理器都是异步的。阻塞式管道 I/O 在具有可配置超时的执行器池中运行。

• 安全管道 —— 管道在做出响度决策前会先测量音频。它们只会降低，绝不会提升。

• 动态工具注册 —— 将模块放入 audacity_mcp/tools/，导出 register(mcp) 函数，它就会被自动发现。

项目结构

AudacityMCP/
├── 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

开发

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

# Run tests
pytest tests/ -x -q

# Run lint (real bugs + security patterns, not style/formatting)
ruff check .

添加新工具

1. 在 audacity_mcp/tools/ 中创建一个模块（或添加到现有模块中）

2. 导出一个 register(mcp: FastMCP) 函数

3. 使用 @mcp.tool() 装饰器定义你的工具

4. 就这样——工具注册表会在启动时自动发现它

# 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)

完整指南请参阅 CONTRIBUTING.md。

社区

要把这个项目变成每个 Audacity 用户都会使用的工具，仅靠一个人是不够的。如果你正在使用 AudacityMCP——哪怕只是试用——欢迎加入 Discord：分享你的成果、报告遇到的问题、建议缺失的功能，或者只是和其他从事 AI 驱动音频编辑的人交流。社区是靠口口相传壮大的，所以如果你认识有人会从中受益，就把链接发给他们。

支持

如果 AudacityMCP 为你节省了时间或对你的音频项目有所帮助，请考虑赞助：

你的支持有助于这个项目持续维护并免费提供给所有人。

文档

• 安装指南 —— Windows、macOS、Linux 的详细设置

• 工具参考 —— 全部 144 个工具的完整参考，包含参数和范围

• 基于转录本的编辑 —— 播客、访谈和讲座的工作流指南（标签驱动编辑）

• 贡献指南 —— 如何添加工具并做出贡献

• 更新日志 —— 版本历史和发布说明

致谢

感谢以下人员报告的 bug、提出的想法和反馈，这些帮助改进了本项目：

• @Harsha-Jay-S —— 通过针对真实 Audacity 的实测证据诊断了 effect_change_pitch/effect_change_speed 的 bug（#15），精确定位了根本原因。

许可证

Apache License 2.0 —— 详情请参阅 LICENSE。

由 Daniel Hodgetts 构建 • 𝕏 @daehonz1