AudacityMCP

AudacityMCP는 MCP 호환 AI 어시스턴트를 Audacity에 연결하여, 이펙트, 정리, 마스터링, 전사 등 144개의 도구를 통해 오디오 편집을 완전히 제어할 수 있게 해줍니다. AI 어시스턴트에게 말하면 실시간으로 오디오를 편집해 줍니다.

클라우드 없음. 오디오 처리를 위한 API 키 없음. 모든 것이 Audacity의 named pipe 인터페이스를 통해 로컬에서 실행됩니다.

이 프로젝트가 유용하다면, 스타 하나가 다른 사람들이 찾는 데 도움이 됩니다 — 이것이 이 프로젝트의 마케팅 예산 전부입니다. 유지보수를 돕고 싶으신가요? 위의 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/Command Prompt 창에서 계속 진행:

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에서는 Command Prompt/PowerShell, macOS/Linux에서는 Terminal)을 열고 pip install audacity-mcp-server 실행 — 일반적인 PyPI 설치이며, 저장소 클론이 필요 없습니다.

3. Claude Desktop 구성: Claude Desktop 열기 → 설정(기어 아이콘) → 개발자 탭 → 구성 편집 — 그러면 claude_desktop_config.json이 텍스트 편집기에서 열립니다. 이미 있는 다른 서버를 유지하면서 "mcpServers" 블록 안에 다음을 추가하세요:

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

   파일을 저장하고 Claude Desktop을 완전히 재시작하세요(시스템 트레이에서 종료, 창을 닫는 것만으로는 안 됨).

이것이 설치의 전부입니다 — 더 자세한 단계와 OS별 참고 사항은 설치 가이드를 참조하세요.

재시작 후 "audacity"가 도구로 표시되지 않나요? 위의 "command": "audacity-mcp"는 해당 명령이 Claude Desktop 자체가 사용하는 PATH에 있을 때만 작동합니다. 항상 그런 것은 아닙니다(특히 Python 설치 시 Claude Desktop이 이미 열려 있던 경우). 연결되지 않으면 터미널에서 실제 설치 위치를 확인하세요: python -c "import sysconfig; print(sysconfig.get_path('scripts'))" — 그런 다음 위의 "audacity-mcp"를 출력된 전체 경로에 \audacity-mcp.exe(Windows, 백슬래시는 두 번 입력: \\) 또는 /audacity-mcp(macOS/Linux)를 붙인 값으로 교체하세요.

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의 named pipe를 통해 통신하므로 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 — 크리에이티브 로파이 / 빈티지

따뜻하고 빈티지한 로파이 사운드를 적용합니다. 프리셋: 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-20dB 증폭시켜 망가뜨릴 수 있습니다. 정리와 음량을 분리하면 최종 음량 단계 전에 결과를 확인할 수 있습니다.

로컬 전사 (실험적)

이 기능은 실험적이며 별도 설정이 필요합니다. 다른 모든 기능은 이 기능 없이도 작동합니다.

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과 다른 Python에서 audacity-mcp를 실행하고 있다는 뜻입니다 — 해결 방법을 참조하세요 (수동 설정 편집, 5분 소요).

새로운 기능 — 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, 라이브 NR 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 사용.

• 전 구간 비동기 — 모든 도구 핸들러는 async입니다. 차단 파이프 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개 전체 도구의 완전한 참조

• 대본 기반 편집 — 팟캐스트, 인터뷰, 강의를 위한 워크플로 가이드 (레이블 기반 편집)

• 기여하기 — 도구 추가 및 기여 방법

• 변경 로그 — 버전 기록 및 릴리스 노트

감사의 말

버그 신고, 아이디어, 그리고 이 프로젝트를 개선한 피드백을 보내주신 분들께 감사드립니다:

• @Harsha-Jay-S — 실제 Audacity에 대한 측정 증거로 effect_change_pitch/effect_change_speed 버그(#15)를 진단하고 정확한 근본 원인을 찾아냈습니다.

라이선스

Apache License 2.0 — 자세한 내용은 LICENSE를 참조하세요.

Daniel Hodgetts 제작 • 𝕏 @daehonz1