Model Context Protocol을 통한 REAPER에서의 AI 기반 음악 제작

빠른 시작 • 기능 • 도구 참조 • 아키텍처 • 문제 해결

ReaperMCP는 MCP 호환 AI 어시스턴트를 REAPER에 연결하여, 24개 모듈에 걸친 153개의 도구를 통해 음악 제작에 대한 완전한 제어권을 부여합니다. 여기에는 트랜스포트 (transport), 트랙 (tracks), MIDI, 패턴 (drum / chord progressions), 루프 라이브러리 파이프라인 (폴더 스캔 → BPM/Key별 선택 → REAPER로 로드), FX, 엔벨로프 (envelopes), 사이드체인 (sidechain), 믹싱 (mixing), 마스터링 (mastering), 버스 파이프라인 (bus pipelines), 그리고 객관적 오디오 분석 (objective audio analysis)이 포함됩니다. AI 어시스턴트와 대화하면 AI가 모든 음표, 리듬, CC를 직접 선택하며 실시간으로 음악을 작곡, 믹싱, 마스터링하고 측정합니다.

ReaperMCP 자체는 REAPER 내부의 파일 기반 Lua IPC 브리지(bridge)를 통해 사용자의 로컬 머신에서 완전히 실행됩니다 — 사용자의 프로젝트, 오디오, MIDI는 컴퓨터를 절대 떠나지 않습니다. AI "두뇌"는 사용자가 이미 실행 중인 곳, 즉 Claude Desktop / Claude Code / Cursor / Antigravity / 기타 모든 MCP 클라이언트에서 자연스럽게 작동합니다. 사용자는 AI를 가져오기만 하면 되며, ReaperMCP가 REAPER를 처리합니다.

ReaperMCP는 Model Context Protocol을 지원하는 모든 AI 클라이언트와 작동합니다:

• Claude Desktop — Anthropic의 데스크톱 앱
• Claude Code — CLI 에이전트
• Cursor — MCP를 지원하는 AI 코드 에디터
• 기타 모든 MCP 호환 클라이언트

옵션 A: 상단의 초록색 Code 버튼 클릭 → Download ZIP → 폴더에 압축 해제

옵션 B: git으로 클론(Clone):

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

폴더를 열고 다음을 실행하세요:

Windows: install.bat를 더블 클릭

macOS / Linux: 폴더에서 터미널을 열고 bash install.sh 실행

설치 프로그램은 reaper-mcp를 로컬에 설치하며, 선택적으로 Claude Desktop을 구성합니다 — 수동으로 JSON을 편집할 필요가 없습니다.

수동 설치 / 기타 MCP 클라이언트 (Cursor, Claude Code 등)

저장소(repo) 폴더에서 pip install -e .를 사용하여 수동으로 설치하고 클라이언트의 MCP 설정에 추가하세요:

{
"mcpServers": {
"reaper": {
...

설정 파일 위치는 사용 중인 클라이언트의 MCP 문서를 확인하세요.

• REAPER 열기 - Actions → Show action list로 이동 - 클릭
  Load ReaScript... 클릭 - reaper_scripts/reaper_mcp_server.lua 경로로 이동하여
  해당 파일을 선택 - 클릭
  Run 클릭

스크립트는 한 번만 로드하면 됩니다 — REAPER가 이를 기억합니다. MCP가 작동하려면 반드시 스크립트가 실행 중이어야 합니다.

AI 클라이언트를 열고 대화를 시작하세요:

"4개의 트랙을 생성해줘: 현악기(strings), 금관악기(brass), 피아노(piano), 드럼(drums)"
"D 단조(D minor)로 8마디 오케스트라 현악 편곡을 해줘"
"피아노 트랙에 ReaEQ를 추가하고 200Hz 미만의 저역대를 깎아줘"
...

REAPER가 열려 있어야 하며 Lua 스크립트가 실행 중이어야 합니다. ReaperMCP는 파일 기반 IPC (Inter-Process Communication)를 통해 통신하므로, 사용자를 대신해 REAPER를 직접 실행할 수는 없습니다.

모든 플랫폼 및 MCP 클라이언트에 대한 상세한 설정 방법은 전체 설치 가이드(Installation Guide)를 참조하세요.

카테고리	도구 수	주요 기능
Transport (트랜스포트)	11	재생(Play), 정지(Stop), 일시정지(Pause), 녹음(Record), BPM 설정, 박자(Time signature) 설정, 재생 속도(Playrate), 반복/메트로놈 토글
Tracks (트랙)	18	생성, 삭제, 이름 변경, 볼륨(Volume), 팬(Pan), 뮤트(Mute), 솔로(Solo), 암(Arm), 색상, 입력(Input), 폴더, 믹서 상태, 피크 미터(Peak meter), 프리즈/언프리즈(Freeze/Unfreeze)
Track Templates (트랙 템플릿)	4	REAPER 트랙 템플릿 저장, 적용, 목록 보기 및 삭제
Project (프로젝트)	11	새로 만들기, 열기, 저장, 오디오 내보내기 (WAV/MP3/OGG/FLAC/AIFF), 실행 취소/다시 실행(Undo/Redo), 노트(Notes), 그리드(Grid)
Items (아이템)	13	아이템 가져오기/선택/분할/삭제/이동, 길이/볼륨/뮤트/페이드 설정, 미디어 삽입, MIDI 생성
Takes (테이크)	4	활성 테이크 목록 보기, 추가, 삭제 및 전환
MIDI	13	노트 삽입 (단일/일괄), 노트 편집/삭제, CC 삽입/삭제, 이벤트 개수 확인, 노트 이름, 정렬, 범위 설정 (CC 읽기는 의도적으로 생략됨 — 아래 참조)
MIDI Quantize / Humanize (MIDI 퀀타이즈 / 휴머나이즈)	3	midi_quantize, midi_humanize, project_set_ripple_mode
Markers & Regions (마커 및 리전)	6	마커/리전 추가, 삭제, 편집, 탐색 (+ Composition Editing의 add_markers_batch)
Tempo Map (템포 맵)	4	템포 마커 추가/삭제/목록 보기, 모두 삭제
Envelopes (엔벨로프)	3	오토메이션 엔벨로프(트랙 / 아이템 / FX-파라미터) 읽기, 쓰기 및 삭제
Selection (선택)	9	시간 선택(Time selection), 루프 포인트, 모든 아이템/트랙 선택/선택 해제, 선택 항목 가져오기
Sends & Routing (센드 및 라우팅)

7 | 센드(sends) 생성/제거, 볼륨/팬/뮤트 설정, 전체 라우팅 다이어그램 |
FX |
15 | 플러그인(plugins) 추가/제거, 파라미터(parameters) 가져오기/설정, 프리셋(presets), 활성화/비활성화, UI 표시, 악기 찾기, 체인 내 이동, 디스플레이 레이블 이름 변경 |
FX 인벤토리 (FX Inventory) |
2 | fx_list_installed (FabFilter / Waves / iZotope / Valhalla / racks 감지), set_fx_preferences |
믹스 및 마스터 (Mix & Master) |
3 | engine_mix, engine_master, engine_fix_mix — EDM / Rock / Pop / Electronic 전반에 걸친 25가지 스타일 프로필 |
사이드체인 (Sidechain) |
1 | setup_sidechain — 단일 amount 다이얼로 핀 매핑된 킥→베이스/패드 펌핑(pumping) 구현 |
버스 파이프라인 (Bus Pipelines) |
4 | setup_parallel_compression, setup_drum_bus, setup_vocal_chain, bounce_stems |
작곡 유틸리티 (Composition Utility) |
3 | get_track_instruments, analyze_score, compose_arrangement (소규모 배치 삽입) |
작곡 편집 (Composition Editing) |
9 | wipe_all_midi, reset_composition, configure_tracks, setup_routing, add_markers_batch, rewrite_cc, edit_section, setup_fx_chain, setup_effect_bus |
패턴 (Patterns) |
2 | create_drum_pattern (멀티 레인 스텝 시퀀서 표기법), create_chord_progression ("Cm7, Fm7, Bb7, Eb"를 보이스가 입혀진 MIDI로 파싱) |
루프 라이브러리 (Loop Library) |
3 | scan_audio_folder (파일명에서 BPM / 키 / 역할 파싱), detect_common_bpm, load_loops (트랙 배치 생성 + 스템(stems) 로드). 샘플 팩 폴더를 지정하면 AI가 이를 기반으로 트랙을 구축합니다. |
오디오 분석 (Audio Analysis) |
4 | analyze_loudness (LUFS vs. 스트리밍/방송/시네마 타겟), analyze_clipping, analyze_frequency_spectrum, analyze_stereo_field — 측정 → 수정 루프를 위한 객관적인 믹스 지표. 선택적 추가 기능: pip install 'reaper-mcp[analysis]' |
데모 (Demo) |
1 | demo_edm_project — 원샷 전체 프로젝트 데모 렌더링 (스모크 테스트 + 레퍼런스) |

모든 시그니처(signature)와 각 도구에 대한 한 줄 설명을 포함한 전체 도구 참조는 docs/TOOLS.md를 확인하세요.

기본 147개 도구 서피스(surface)는 모든 기능을 갖춘 프런티어 모델(frontier models)을 위해 설계되었습니다. 더 작거나 저렴한 모델(Groq Llama 3는 128개 도구로 제한되며, 일부 로컬 모델은 이보다 더 적음)은 도구가 조용히 잘릴(truncate) 수 있습니다. 워크플로별 특정 하위 집합을 선택하려면 클라이언트의 서버 설정에서 REAPER_MCP_PROFILE을 설정하세요:

프로필 (Profile)	도구 수 (Tools)	용도 (For)
full (기본값)	~153	프런티어 모델 (Frontier models) — Claude, GPT-4, Gemini
composition	~109	음악 작곡 / 편집 (패턴 + 루프 포함)
mixing	~67	믹싱, 마스터링, 버스 파이프라인 (bus pipelines)
analysis	~47	검사 + 측정 전용
minimal	~40	스모크 테스트 (Smoke test) / 기본 제어

{
"mcpServers": {
"reaper": {
...

25가지 전문가 스타일 프로필이 자동 EQ, 컴프레션 (compression), 리버브 버스 (reverb buses), 사이드체인 펌핑 (sidechain pumping) 및 마스터링을 구동하며, 각 프로필은 업계 표준 LUFS 목표값과 캐릭터에 맞춰 조정되었습니다.

도구 (Tool)	기능 (What It Does)
engine_mix(style)	트랙별 EQ + 컴프레션 (compression) + 센드 라우팅 (send routing)이 포함된 리버브 버스 (reverb buses). FabFilter Pro-Q 3 / Pro-C 2 / Pro-R을 자동 감지하거나 REAPER 기본 플러그인 (ReaEQ / ReaComp / ReaVerbate)으로 대체함
engine_master(style)	마스터 버스 체인 (Master-bus chain): HP 25 Hz → 버스 글루 컴프 (bus glue comp) → 토널 쉘프 EQ (tonal shelf EQ) → 스테레오 너비 (stereo width) → 브릭월 리미터 (brick-wall limiter). 스타일별 LUFS 및 트루 피크 (true-peak) 천장값을 목표로 함
engine_fix_mix(style)	비파괴적 복구 패스 (Non-destructive repair pass) — 기존 세션에 믹스 파이프라인을 다시 실행하며, 가능한 경우 사용자의 미세 조정 사항을 보존함
setup_sidechain(source, target, amount)	채널 3/4 + 핀 매핑된 사이드체인 입력을 통한 킥(Kick) → 베이스/패드(bass/pad) 펌핑
setup_drum_bus / setup_parallel_compression / setup_vocal_chain	드럼, 패러럴 (NY) 컴프레션 (parallel compression), 프로 보컬 체인을 위한 즉석 버스 레시피
bounce_stems(track_indices)	선택된 트랙들을 개별 WAV 스템 (stems)으로 렌더링

스타일 (Styles) (25개):

EDM (11): melodic_dubstep, big_room, future_bass, future_house, deep_house, tech_house, progressive_house, dubstep, trap, drum_and_bass, trance

Rock (6): alt_rock, classic_rock, pop_rock, hard_rock

,punk

,post_rock

Pop (4): modern_pop

,dance_pop

,indie_pop

,rnb_pop

Electronic (4): synthwave

,lofi

,ambient

,hiphop

스마트 플러그인 감지 (Smart plugin detection). fx_list_installed()는 사용자의 머신에 설치된 항목을 조사하여 사용 가능한 최적의 EQ / compressor (컴프레서) / reverb (리버브) / limiter (리미터) / de-esser (디에서) / gate (게이트) / saturator (새츄레이터) / multiband (멀티밴드) / stereo tool (스테레오 툴)을 보고합니다. 이는 FabFilter, Waves, iZotope, Valhalla, Softube, TDR, Slate, Melda, Soundtoys, Airwindows, REAPER 기본 플러그인 및 일반적인 랙 호스트(Waves StudioRack, Blue Cat PatchWork, Kilohearts Snap Heap)를 모두 포함합니다. 사용자는 set_fx_preferences(...)를 통해 카테고리 → 플러그인 선호도를 고정할 수 있습니다.

AI는 위의 세밀한 MIDI 및 FX 도구들을 사용하여 모든 노트, 리듬, CC 커브, keyswitch (키스위치)를 직접 작성합니다. 단일 00_core.md 지시 파일이 도구 인터페이스, 약어 표기법, BBC Spitfire CC 참조, 그리고 장르별 믹싱 팁을 제공합니다. Voicing (보이싱), humanization (휴머나이제이션), 구조 및 장르 관습은 모두 AI 자체의 음악적 지식에서 비롯됩니다.

┌──────────────┐ stdio ┌──────────────┐ file IPC ┌──────────────┐
│ MCP Client │◄──────────────►│ ReaperMCP │◄────────────►│ REAPER │
│(AI assistant)│ (JSON-RPC) │ FastMCP │ (JSON files) │ (Lua script)│
...

Python 서버는 공유 임시 디렉토리의 command.json에 명령을 작성하며, REAPER 내부의 Lua 스크립트가 이를 폴링(polling)하여 실행하고 결과를 response.json에 작성합니다. 소켓, 포트, 네트워크 노출이 없습니다.

IPC 디렉토리:

• Windows:
  %TEMP%\reaper_mcp

• macOS:
  $TMPDIR/reaper_mcp

• Linux:
  /tmp/reaper_mcp

파일 기반 IPC (File-based IPC) — 포트 할당 없음, 방화벽 노출 없음.
정적 Lua 디스패치 (Static Lua dispatch) — 모든 핸들러는 명시적인 코드이며, load / dofile / loadstring을 사용하지 않음.
동적 도구 등록 (Dynamic tool registration) — reaper_mcp/tools/에 모듈을 넣고 register(mcp)를 export하면 자동으로 인식됨.
하트비트 + 타임아웃 (Heartbeat + timeouts) — 클라이언트는 REAPER이 응답하지 않는 상태(lock-file 업데이트 없음)를 감지하고, 시스템이 멈추는 대신 타입화된 에러(typed error)를 발생시킴.
보수적인 호출당 제한 (Conservative per-call limits) — MAX_COMPOSE_TRACKS

, MAX_TOTAL_NOTES_PER_CALL

등등. 어떠한 단일 명령도 REAPER 메인 스레드 점유 시간이 약 2초를 넘지 않도록 유지하세요.

상세 내용 — IPC 프로토콜, 요청 라이프사이클 (request lifecycle), 등록 내부 로직 (registration internals), 믹스 엔진 파이프라인 (mix-engine pipeline), 스타일 카탈로그 (style catalog) — 은

docs/ARCHITECTURE.md 에 있습니다.

Reaper-MCP/
├── reaper_mcp/
│ ├── main.py # FastMCP 서버 엔트리 (`reaper-mcp` 명령)
...

ReaperMCP가 REAPER를 제어하지만, AI가 작곡할 수 있도록 악기(instruments)가 로드되어 있어야 합니다. AI는 트랙을 생성하고 MIDI를 작성할 수는 있지만, 사용자를 대신해 VST 플러그인을 탐색하거나 설치할 수는 없습니다.

REAPER를 열고
새 프로젝트를 생성하세요
원하는 VST 악기(Kontakt, Spitfire, LABS 등)로 트랙을 추가하세요
패치(patches)를 로드하세요 — 예: "Violin 1 Legato", "French Horn a4", "Grand Piano"
템플릿으로 저장하세요(File → Save Project As Template) 매번 이 과정을 반복하지 않도록

AI는 get_track_instruments를 사용하여

무엇이 로드되어 있는지 감지하고 해당 악기들에 맞춰 자동으로 작곡합니다.

권장되는 악기 템플릿(오케스트라, 팝/락, EDM) 및 로드해야 할 플러그인에 대한 자세한 내용은

Project Setup Guide를 참조하세요.

문제	해결 방법
"REAPER로부터 응답 없음"	REAPER가 열려 있고 Lua 스크립트가 실행 중인지 확인하세요. Actions → Show action list → reaper_mcp_server.lua를 찾아 → Run을 클릭하세요.
...

# 개발 의존성 설치
pip install -e ".[dev]"
# 테스트 실행
...

• reaper_mcp/tools/ 안에 모듈을 생성하거나 (또는 기존 모듈에 추가)
• register(mcp: FastMCP) 함수를 내보내기(Export)
• @mcp.tool() 데코레이터로 도구(tools) 정의
• 이것으로 끝입니다 — 도구 레지스트리(tool registry)가 시작 시 이를 자동으로 감지합니다.

전체 가이드라인은 CONTRIBUTING.md를 참조하세요.

ReaperMCP가 음악 제작에 도움이 되었다면, 커피 한 잔을 구매해 주세요:

여러분의 후원은 이 프로젝트를 유지하고 모두에게 무료로 제공하는 데 큰 도움이 됩니다.

설치 가이드 (Installation Guide)— Windows, macOS, Linux 및 모든 지원되는 MCP 클라이언트를 위한 상세 설정
프로젝트 설정 가이드 (Project Setup Guide)— AI 작곡을 위한 악기 구성 및 REAPER 프로젝트 설정
도구 참조 (Tools Reference)— 도메인별로 그룹화된 모든 도구, 한 줄 설명 및 시그니처 포함
아키텍처 (Architecture)— IPC 프로토콜 (IPC protocol), Lua 브리지 (Lua bridge), 동적 도구 등록 (dynamic tool registration), 믹스 엔진 파이프라인 (mix-engine pipeline), 스타일 카탈로그 (style catalog)
기여하기 (Contributing)— 도구 추가 및 기여 방법
변경 이력 (Changelog)— 버전 기록 및 릴리스 노트

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

Built by Daniel Hodgetts • 𝕏 @daehonz1