AI-powered music production in REAPER through the Model Context Protocol
Quick Start • Features • Tools Reference • Architecture • Troubleshooting
ReaperMCP connects any MCP-compatible AI assistant to REAPER, giving it full control over music production through 153 tools across 24 modules — transport, tracks, MIDI, patterns (drum / chord progressions), loop-library pipeline (scan folder → pick by BPM/key → load into REAPER), FX, envelopes, sidechain, mixing, mastering, bus pipelines, and objective audio analysis. Talk to your AI assistant and it composes, mixes, masters, and measures your music in real-time — the AI chooses every note, rhythm, and CC itself.
ReaperMCP itself runs entirely on your machine via a file-based Lua IPC bridge inside REAPER — your project, audio, and MIDI never leave your computer. The AI "brain" naturally lives wherever you already run it: Claude Desktop / Claude Code / Cursor / Antigravity / any MCP client. You bring the AI, ReaperMCP handles REAPER.
ReaperMCP works with any AI client that supports the Model Context Protocol:
- Claude Desktop — Anthropic's desktop app
- Claude Code — CLI agent
- Cursor — AI code editor with MCP support
- Any other MCP-compatible client
Option A: Click the green Code button above → Download ZIP → extract to a folder
Option B: Clone with git:
git clone https://github.com/xDarkzx/Reaper-MCP.gitOpen the folder and run:
- Windows: Double-click
install.bat - macOS / Linux: Open terminal in the folder and run
bash install.sh
The installer installs
reaper-mcplocally and optionally configures Claude Desktop — no manual JSON editing needed.
Manual install / other MCP clients (Cursor, Claude Code, etc.)
Install manually with pip install -e . from the repo folder and add to your client's MCP config:
{
"mcpServers": {
"reaper": {
"command": "reaper-mcp"
}
}
}Check your client's MCP documentation for the config file location.
- Open REAPER
- Go to Actions → Show action list
- Click Load ReaScript...
- Navigate to
reaper_scripts/reaper_mcp_server.luaand select it - Click Run
You only need to load the script once — REAPER remembers it. The script must be running for MCP to work.
Open your AI client and start talking:
"Create 4 tracks: strings, brass, piano, and drums"
"Compose an 8-bar orchestral string arrangement in D minor"
"Add ReaEQ to the piano track and cut the low end below 200Hz"
"Set the tempo to 90 BPM and loop the first 8 bars"
REAPER must be open with the Lua script running. ReaperMCP communicates through file-based IPC — it can't launch REAPER for you.
See the full Installation Guide for detailed setup on all platforms and MCP clients.
| Category | Tools | Highlights |
|---|---|---|
| Transport | 11 | Play, stop, pause, record, set BPM, time signature, playrate, toggle repeat/metronome |
| Tracks | 18 | Create, delete, rename, volume, pan, mute, solo, arm, colour, input, folder, mixer state, peak meter, freeze/unfreeze |
| Track Templates | 4 | Save, apply, list, and delete REAPER track templates |
| Project | 11 | New, open, save, export audio (WAV/MP3/OGG/FLAC/AIFF), undo/redo, notes, grid |
| Items | 13 | Get/select/split/delete/move items, set length/volume/mute/fade, insert media, create MIDI |
| Takes | 4 | List, add, delete, and switch active take |
| MIDI | 13 | Insert notes (single/batch), edit/delete notes, insert/delete CC, count events, note names, sort, set extents (CC reading intentionally omitted — see below) |
| MIDI Quantize / Humanize | 3 | midi_quantize, midi_humanize, project_set_ripple_mode |
| Markers & Regions | 6 | Add markers/regions, delete, edit, navigate (+ add_markers_batch in Composition Editing) |
| Tempo Map | 4 | Add/delete/list tempo markers, clear all |
| Envelopes | 3 | Read, write, and clear automation envelopes (track / item / FX-param) |
| Selection | 9 | Time selection, loop points, select/deselect all items/tracks, get selected |
| Sends & Routing | 7 | Create/remove sends, set volume/pan/mute, full routing diagram |
| FX | 15 | Add/remove plugins, get/set parameters, presets, enable/disable, show UI, find instrument, move within chain, rename display label |
| FX Inventory | 2 | fx_list_installed (detects FabFilter / Waves / iZotope / Valhalla / racks), set_fx_preferences |
| Mix & Master | 3 | engine_mix, engine_master, engine_fix_mix — 25 style profiles across EDM / Rock / Pop / Electronic |
| Sidechain | 1 | setup_sidechain — pin-mapped kick→bass/pad pumping with a single amount dial |
| Bus Pipelines | 4 | setup_parallel_compression, setup_drum_bus, setup_vocal_chain, bounce_stems |
| Composition Utility | 3 | get_track_instruments, analyze_score, compose_arrangement (small batch insert) |
| 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 (multi-lane step-sequencer notation), create_chord_progression (parses "Cm7, Fm7, Bb7, Eb" into voiced MIDI) |
| Loop Library | 3 | scan_audio_folder (parse BPM / key / role from filenames), detect_common_bpm, load_loops (batch-create tracks + load stems). Point at a sample-pack folder and the AI builds a track from it. |
| Audio Analysis | 4 | analyze_loudness (LUFS vs. streaming/broadcast/cinema target), analyze_clipping, analyze_frequency_spectrum, analyze_stereo_field — objective mix metrics for measure → correct loops. Optional extras: pip install 'reaper-mcp[analysis]' |
| Demo | 1 | demo_edm_project — one-shot full-project demo render (smoke test + reference) |
See docs/TOOLS.md for the complete tool reference with every signature and a one-line description for each tool.
The default 147-tool surface is designed for full-featured frontier models. Smaller/cheaper models (Groq Llama 3 caps at 128 tools, some local models lower still) will silently truncate. Set REAPER_MCP_PROFILE in your client's server config to pick a workflow-specific subset:
| Profile | Tools | For |
|---|---|---|
full (default) |
~153 | Frontier models — Claude, GPT-4, Gemini |
composition |
~109 | Writing / editing music (includes patterns + loops) |
mixing |
~67 | Mixing, mastering, bus pipelines |
analysis |
~47 | Inspect + measure only |
minimal |
~40 | Smoke test / basic control |
{
"mcpServers": {
"reaper": {
"command": "reaper-mcp",
"env": { "REAPER_MCP_PROFILE": "mixing" }
}
}
}25 professional style profiles drive automatic EQ, compression, reverb buses, sidechain pumping, and mastering — each tuned to industry-standard LUFS targets and character.
| Tool | What It Does |
|---|---|
engine_mix(style) |
Per-track EQ + compression + reverb buses with send routing. Auto-detects FabFilter Pro-Q 3 / Pro-C 2 / Pro-R or falls back to REAPER stock (ReaEQ / ReaComp / ReaVerbate) |
engine_master(style) |
Master-bus chain: HP 25 Hz → bus glue comp → tonal shelf EQ → stereo width → brick-wall limiter, targeting style-specific LUFS and true-peak ceilings |
engine_fix_mix(style) |
Non-destructive repair pass — re-runs the mix pipeline on an existing session, preserving user tweaks where possible |
setup_sidechain(source, target, amount) |
Kick → bass / pad pumping via channels 3/4 + pin-mapped sidechain inputs |
setup_drum_bus / setup_parallel_compression / setup_vocal_chain |
Ready-made bus recipes for drums, parallel (NY) comp, and pro vocal chains |
bounce_stems(track_indices) |
Render selected tracks individually to 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() inspects what's on the user's machine and reports the best-available EQ / compressor / reverb / limiter / de-esser / gate / saturator / multiband / stereo tool — covering FabFilter, Waves, iZotope, Valhalla, Softube, TDR, Slate, Melda, Soundtoys, Airwindows, REAPER stock, and common rack hosts (Waves StudioRack, Blue Cat PatchWork, Kilohearts Snap Heap). Users can pin category → plugin preferences via set_fx_preferences(...).
The AI writes every note, rhythm, CC curve, and keyswitch itself using the granular MIDI and FX tools above. A single 00_core.md instruction file provides the tool surface, shorthand notation, BBC Spitfire CC reference, and per-family mixing tips. Voicing, humanization, structure, and genre conventions all come from the AI's own musical knowledge.
┌──────────────┐ stdio ┌──────────────┐ file IPC ┌──────────────┐
│ MCP Client │◄──────────────►│ ReaperMCP │◄────────────►│ REAPER │
│(AI assistant)│ (JSON-RPC) │ FastMCP │ (JSON files) │ (Lua script)│
└──────────────┘ └──────────────┘ └──────────────┘
The Python server writes commands to command.json in a shared temp directory; a Lua script inside REAPER polls, executes, and writes results to response.json. No sockets, no ports, no network exposure.
IPC directory:
- Windows:
%TEMP%\reaper_mcp - macOS:
$TMPDIR/reaper_mcp - Linux:
/tmp/reaper_mcp
- File-based IPC — no port allocation, no firewall surface.
- Static Lua dispatch — every handler is explicit code, no
load/dofile/loadstring. - Dynamic tool registration — drop a module into
reaper_mcp/tools/, exportregister(mcp), and it's picked up automatically. - Heartbeat + timeouts — the client detects a stale REAPER (no lock-file update) and raises a typed error instead of hanging.
- Conservative per-call limits —
MAX_COMPOSE_TRACKS,MAX_TOTAL_NOTES_PER_CALLetc. keep any single command under ~2 s of REAPER's main thread time.
Full details — IPC protocol, request lifecycle, registration internals, mix-engine pipeline, style catalog — in docs/ARCHITECTURE.md.
Reaper-MCP/
├── reaper_mcp/
│ ├── main.py # FastMCP server entry (`reaper-mcp` command)
│ ├── tool_registry.py # Auto-discovers tool modules
│ ├── reaper_client.py # File-IPC client (lock, heartbeat, timeouts)
│ ├── cc_map.py # CC number translation helpers
│ ├── shorthand.py # Compact composition notation parser
│ ├── instructions/
│ │ └── 00_core.md # System-prompt instructions injected into MCP
│ ├── mix_engine/ # Mixing + mastering pipelines
│ │ ├── __init__.py # run_mix_pipeline
│ │ ├── master.py # run_master_pipeline
│ │ ├── fix_mix.py # Non-destructive mix repair
│ │ ├── detect.py # FabFilter / REAPER stock detection
│ │ ├── fx_inventory.py # Installed-plugin discovery
│ │ ├── plugins.py # Plugin param translation
│ │ ├── profiles.py # Legacy orchestral profiles
│ │ ├── profiles_v2.py # Schema for 25 style profiles
│ │ └── catalog/ # Per-family style catalog
│ │ ├── edm.py # 11 EDM subgenres
│ │ ├── rock.py # 6 rock subgenres
│ │ ├── pop.py # 4 pop subgenres
│ │ ├── electronic.py # synthwave, lofi, ambient, hiphop
│ │ └── _shared.py # Shared role → EQ/comp library
│ └── tools/ # 24 modules, 153 auto-registered tools
│ ├── transport_tools.py # Playback and recording (11)
│ ├── track_tools.py # Track management + freeze (18)
│ ├── template_tools.py # Track templates (4)
│ ├── project_tools.py # Project/file operations (11)
│ ├── item_tools.py # Media item management (13)
│ ├── take_tools.py # Takes (4)
│ ├── midi_tools.py # MIDI notes and CC (13)
│ ├── quantize_tools.py # Quantize / humanize / ripple (3)
│ ├── marker_tools.py # Markers and regions (6)
│ ├── tempo_tools.py # Tempo map markers (4)
│ ├── envelope_tools.py # Automation envelopes (3)
│ ├── selection_tools.py # Selection and loop (9)
│ ├── send_tools.py # Sends and routing (7)
│ ├── fx_tools.py # FX chain + params (14)
│ ├── inventory_tools.py # fx_list_installed + set_fx_preferences (2)
│ ├── mix_tools.py # engine_mix / engine_master / engine_fix_mix (3)
│ ├── sidechain_tools.py # setup_sidechain (1)
│ ├── pipeline_tools.py # Drum bus, parallel comp, vocal chain, stems (4)
│ ├── compose_tools.py # get_track_instruments, analyze_score, compose_arrangement (3)
│ ├── compose_edit_tools.py # wipe_all_midi, edit_section, rewrite_cc, … (9)
│ ├── patterns_tools.py # create_drum_pattern, create_chord_progression (2)
│ ├── loops_tools.py # scan_audio_folder, detect_common_bpm, load_loops (3)
│ ├── analysis_tools.py # LUFS, clipping, spectrum, stereo field (4, optional deps)
│ ├── demo_tools.py # demo_edm_project (1)
│ └── compose_helpers.py # Shared helpers (no tools)
├── reaper_mcp_shared/
│ ├── constants.py # IPC paths, timeouts, safety limits
│ ├── error_codes.py # ReaperMCPError + ErrorCode enum
│ └── protocol.py # Command / response formatting
├── reaper_scripts/
│ └── reaper_mcp_server.lua # Lua IPC bridge (runs inside REAPER)
├── docs/
│ ├── INSTALLATION.md # Detailed setup for all platforms
│ ├── PROJECT_SETUP.md # Template setups for orchestral / pop / EDM
│ ├── TOOLS.md # Complete tool reference
│ └── ARCHITECTURE.md # IPC protocol, mix engine, design notes
├── tests/
├── install.bat / install.sh # One-click installers
├── CHANGELOG.md
├── CONTRIBUTING.md
├── LICENSE
└── pyproject.toml
ReaperMCP controls REAPER — but you need instruments loaded for the AI to compose with. The AI can create tracks and write MIDI, but it can't browse or install VST plugins for you.
- Open REAPER and create a new project
- Add tracks with your desired VST instruments (Kontakt, Spitfire, LABS, etc.)
- Load patches — e.g., "Violin 1 Legato", "French Horn a4", "Grand Piano"
- Save as a template (File → Save Project As Template) so you don't repeat this every time
The AI will use get_track_instruments to detect what's loaded and compose for those instruments automatically.
See the full Project Setup Guide for recommended instrument templates (orchestral, pop/rock, EDM) and what plugins to load.
| Problem | Fix |
|---|---|
| "No response from REAPER" | Make sure REAPER is open and the Lua script is running. Go to Actions → Show action list → find reaper_mcp_server.lua → Run. |
| Script not found in Actions | Click Load ReaScript... first to register it, then Run. |
| "Connection timeout" | REAPER is busy. Wait for it to finish, or check if the Lua script crashed (re-run it). |
| Works once then stops | The Lua script may have stopped. Re-run it from Actions. |
| Claude Desktop doesn't see ReaperMCP | Restart Claude Desktop after editing the config. Check %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS). |
| "command not found: reaper-mcp" | Run the installer again, or manually: pip install -e . from the repo folder. |
| MIDI notes sound robotic | Make sure your AI is using the humanization instructions — ask it to "humanize the MIDI" or "add expression CC curves". |
# Install dev dependencies
pip install -e ".[dev]"
# Run tests
pytest tests/ -x -q- Create a module in
reaper_mcp/tools/(or add to an existing one) - Export a
register(mcp: FastMCP)function - Define your tools with
@mcp.tool()decorators - That's it — the tool registry auto-discovers it on startup
See CONTRIBUTING.md for full guidelines.
If ReaperMCP has helped with your music production, consider buying me a coffee:
Your support helps keep this project maintained and free for everyone.
- Installation Guide — Detailed setup for Windows, macOS, Linux and every supported MCP client
- Project Setup Guide — Setting up your REAPER project with instruments for AI composition
- Tools Reference — Every tool grouped by domain, with a one-line description and signature
- Architecture — IPC protocol, Lua bridge, dynamic tool registration, mix-engine pipeline, style catalog
- Contributing — How to add tools and contribute
- Changelog — Version history and release notes
Apache License 2.0 — see LICENSE for details.
Built by Daniel Hodgetts • 𝕏 @daehonz1