TwelveTake REAPER MCP

1# TwelveTake REAPER MCP
2 
3A [TwelveTake Studios](https://twelvetake.com) project.
4 
5[![Tools](https://img.shields.io/badge/tools-130-blue)](https://github.com/TwelveTake/reaper-mcp)
6[![Buy Me a Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-support-yellow)](https://buymeacoffee.com/twelvetake)
7[![Ko-fi](https://img.shields.io/badge/Ko--fi-support-ff5e5b)](https://ko-fi.com/twelvetake)
8 
9A comprehensive Model Context Protocol (MCP) server that enables AI assistants to control REAPER DAW for mixing, mastering, MIDI composition, and full music production workflows.
10 
11Built by a working producer with 7+ albums released. These aren't theoretical tools—they're battle-tested in real sessions.
12 
13**Version:** 1.1.0
14 
15## Why This Server
16 
17### Workflow Automation, Not Just API Wrappers
18 
19Most MCP servers just wrap REAPER's API and call it a day. This one includes **production workflow helpers** that handle multi-step operations in a single call:
20 
21| Tool | What it does for you |
22|------|---------------------|
23| `setup_sidechain_compression()` | Creates send, routes to channels 3-4, configures ReaComp's detector input — complete sidechain setup in one call |
24| `add_mastering_chain()` | Adds ReaEQ → ReaComp → ReaEQ → ReaLimit to master track with proper signal flow |
25| `add_parallel_compression()` | Creates a bus track, sets up the send, adds compressor — NY-style compression ready to blend |
26| `create_bus()` | Creates a submix track and routes your specified tracks to it |
27| `get_project_summary()` | Returns track count, all track names/volumes/pans/FX, markers, regions, tempo, time signature — everything your AI needs in one call |
28 
29### Zero Configuration
30 
31- **File-based communication** works immediately — no network setup, no ports to configure
32- **Stock REAPER Lua only** — the bridge script has no dependencies, nothing extra to install in REAPER
33- Copy the script, run it, connect your AI assistant
34 
35### 130 Tools Covering Real Production Needs
36 
37- **Full FX control** — add/remove plugins, get/set any parameter by index, manage presets, bypass
38- **Complete routing** — sends, receives, sidechain routing to specific channel pairs
39- **Automation** — create envelopes, add/edit points, set automation modes
40- **MIDI** — create items, add notes individually or in batches, edit velocities
41- **Audio items** — import, split, duplicate, fade, position, mute
42- **Markers & regions** — create, edit, navigate, render by region
43 
44## Requirements
45 
46- REAPER (any recent version)
47- Python 3.8+ (for the MCP server)
48- An MCP-compatible AI assistant (Claude, ChatGPT, etc.)
49 
50## Installation
51 
52### 1. Install the Bridge Script in REAPER
53 
54The bridge script runs inside REAPER and handles communication with the MCP server.
55 
561. Copy `reaper_mcp_bridge.lua` to your REAPER Scripts folder:
57   - Windows: `%APPDATA%\REAPER\Scripts\`
58   - macOS: `~/Library/Application Support/REAPER/Scripts/`
59   - Linux: `~/.config/REAPER/Scripts/`
602. In REAPER: **Actions → Show action list → Load ReaScript**
613. Select `reaper_mcp_bridge.lua` and click **Run**
62 
63You should see "REAPER MCP Bridge started" in REAPER's console.
64 
65### 2. Install the MCP Server
66 
67```bash
68pip install -r requirements.txt
69```
70 
71Or install dependencies directly:
72```bash
73pip install mcp httpx
74```
75 
76### 3. Configure Your AI Assistant
77 
78Add to your MCP configuration (e.g., `~/.claude.json` or `.mcp.json`):
79 
80```json
81{
82  "mcpServers": {
83    "reaper": {
84      "command": "python",
85      "args": ["path/to/reaper_mcp_server.py"]
86    }
87  }
88}
89```
90 
91### 4. Verify Connection
92 
93```bash
94python test_connection.py
95```
96 
97## Communication Modes
98 
99The MCP server supports two communication modes:
100 
101### File-Based (Default)
102 
103Uses JSON files for communication. More reliable, no network configuration needed.
104 
105```
106MCP Server                    REAPER Bridge
107    │                              │
108    ├── writes request_N.json ────►│
109    │                              ├── processes request
110    │◄── reads response_N.json ────┤
111```
112 
113**Bridge directory:** `%APPDATA%\REAPER\Scripts\mcp_bridge_data`
114 
115### HTTP Mode (Advanced)
116 
117Uses HTTP requests on localhost. Requires additional setup:
118- **Lua HTTP bridge**: Requires LuaSocket (install via ReaPack → "sockmonkey")
119- **Python HTTP bridge**: Requires Python enabled in REAPER preferences
120 
121```bash
122# Set environment variable to use HTTP mode
123REAPER_COMM_MODE=http python reaper_mcp_server.py
124```
125 
126**Default port:** 9000
127 
128## Quick Start Examples
129 
130### Basic Track Operations
131```
132"How many tracks are in my project?"
133"Create a new track called 'Vocals'"
134"Set track 0 volume to -6dB"
135"Mute track 2"
136"Solo the drums track"
137```
138 
139### Mixing
140```
141"Add ReaComp to the bass track"
142"Set up sidechain compression from the kick to the bass"
143"Create a drum bus and route tracks 0-3 to it"
144"Add a mastering chain to the master track"
145```
146 
147### FX and Parameters
148```
149"What plugins are on track 0?"
150"Get the parameters for the compressor on track 1"
151"Set the threshold to -20dB"
152"Bypass the EQ on the vocal track"
153```
154 
155### MIDI Composition
156```
157"Create a 4-bar MIDI item on track 0"
158"Add a C major chord at the start"
159"Get all the notes in the MIDI item"
160"Set the velocity of note 0 to 100"
161```
162 
163### Transport and Navigation
164```
165"Play the project"
166"Stop playback"
167"Set the cursor to 30 seconds"
168"Add a marker called 'Chorus' at the current position"
169```
170 
171### Project Management
172```
173"What's the project tempo?"
174"Set the tempo to 120 BPM"
175"Save the project"
176"Render to D:/Output/mix.wav"
177```
178 
179## Tool Reference
180 
181### Track Operations (19 tools)
182 
183| Tool | Description |
184|------|-------------|
185| `get_track_count()` | Get total number of tracks (excluding master) |
186| `get_track(index)` | Get track info (name, volume, pan, mute, solo) |
187| `get_all_tracks()` | Get info for all tracks |
188| `get_master_track()` | Get master track info |
189| `insert_track(index, name)` | Create a new track |
190| `delete_track(index)` | Delete a track |
191| `set_track_name(index, name)` | Rename a track |
192| `set_track_volume(index, db)` | Set volume in dB |
193| `set_track_pan(index, pan)` | Set pan (-1 to 1) |
194| `set_track_mute(index, mute)` | Mute/unmute track |
195| `set_track_solo(index, solo)` | Solo/unsolo track |
196| `set_track_phase(index, invert)` | Invert phase |
197| `set_track_width(index, width)` | Set stereo width (0-2) |
198| `set_track_color(index, r, g, b)` | Set track color |
199| `get_track_peak(index, channel)` | Get current peak level |
200| `set_track_as_folder(index, depth)` | Set as folder parent/child |
201| `arm_track(index, arm)` | Arm for recording |
202| `set_track_input(index, input)` | Set record input |
203| `set_track_monitor(index, mode)` | Set monitor mode |
204 
205### FX Operations (15 tools)
206 
207| Tool | Description |
208|------|-------------|
209| `track_fx_get_count(index)` | Count FX on track |
210| `track_fx_get_list(index)` | List all FX with details |
211| `track_fx_add_by_name(index, name)` | Add FX plugin |
212| `track_fx_delete(index, fx_index)` | Remove FX |
213| `track_fx_get_name(index, fx_index)` | Get FX name |
214| `track_fx_get_enabled(index, fx_index)` | Check if enabled |
215| `track_fx_set_enabled(index, fx_index, enabled)` | Enable/bypass FX |
216| `track_fx_get_num_params(index, fx_index)` | Count parameters |
217| `track_fx_get_param_name(index, fx_index, param)` | Get parameter name |
218| `track_fx_get_param(index, fx_index, param)` | Get parameter value |
219| `track_fx_set_param(index, fx_index, param, value)` | Set parameter value |
220| `get_fx_presets(index, fx_index)` | List available presets |
221| `get_fx_preset(index, fx_index)` | Get current preset |
222| `set_fx_preset(index, fx_index, name)` | Load preset |
223| `save_fx_preset(index, fx_index, name)` | Save current settings as preset |
224 
225### Routing (9 tools)
226 
227| Tool | Description |
228|------|-------------|
229| `create_send(src, dest)` | Create send between tracks |
230| `delete_send(index, send_index)` | Remove a send |
231| `set_send_volume(index, send_index, db)` | Set send level |
232| `get_track_num_sends(index)` | Count sends from track |
233| `set_send_dest_channels(index, send_index, chan)` | Route to specific channels |
234| `set_send_source_channels(index, send_index, chan)` | Set source channels |
235| `setup_sidechain_send(src, dest, db)` | Create sidechain send |
236| `configure_reacomp_sidechain(index, fx_index, use)` | Configure ReaComp sidechain |
237| `setup_sidechain_compression(trigger, target, fx, db)` | Complete sidechain setup |
238 
239### Transport (10 tools)
240 
241| Tool | Description |
242|------|-------------|
243| `play()` | Start playback |
244| `stop()` | Stop playback |
245| `pause()` | Pause playback |
246| `record()` | Start recording |
247| `get_play_state()` | Get current state (playing/paused/recording) |
248| `get_cursor_position()` | Get edit cursor position (seconds) |
249| `set_cursor_position(seconds)` | Move edit cursor |
250| `get_play_position()` | Get playback position (seconds) |
251| `toggle_repeat()` | Toggle loop mode |
252| `get_repeat_state()` | Check if looping |
253 
254### Project (15 tools)
255 
256| Tool | Description |
257|------|-------------|
258| `get_project_summary()` | Get comprehensive project state in one call |
259| `save_project()` | Save current project |
260| `create_project(name)` | Create new project |
261| `open_project(path)` | Open project file |
262| `get_project_path()` | Get project directory |
263| `get_project_name()` | Get project filename |
264| `get_project_length()` | Get project length (seconds) |
265| `get_tempo()` | Get project tempo (BPM) |
266| `set_tempo(bpm)` | Set project tempo |
267| `get_time_signature()` | Get time signature |
268| `set_time_signature(num, denom)` | Set time signature |
269| `render_project(path, start, end, tail)` | Render to audio file |
270| `render_region(index, path)` | Render specific region |
271| `zoom_to_selection()` | Zoom to time selection |
272| `zoom_to_project()` | Zoom to show entire project |
273 
274### MIDI Operations (8 tools)
275 
276| Tool | Description |
277|------|-------------|
278| `create_midi_item(track, pos, length)` | Create empty MIDI item |
279| `get_midi_item(track, item)` | Get MIDI item info |
280| `add_midi_note(track, item, pitch, vel, start, end, chan)` | Add single note |
281| `add_midi_notes_batch(track, item, notes)` | Add multiple notes |
282| `get_midi_notes(track, item)` | Get all notes |
283| `delete_midi_note(track, item, note)` | Delete a note |
284| `clear_midi_item(track, item)` | Delete all notes |
285| `set_midi_note_velocity(track, item, note, vel)` | Change note velocity |
286 
287### Audio Items (17 tools)
288 
289| Tool | Description |
290|------|-------------|
291| `insert_audio_file(track, path, pos)` | Import audio file |
292| `get_track_items(track)` | List all items on track |
293| `get_item_info(track, item)` | Get item details |
294| `set_item_position(track, item, pos)` | Move item |
295| `set_item_length(track, item, length)` | Change item length |
296| `delete_item(track, item)` | Delete item |
297| `duplicate_item(track, item)` | Duplicate item |
298| `split_item(track, item, pos)` | Split item at position |
299| `set_item_mute(track, item, mute)` | Mute/unmute item |
300| `set_item_volume(track, item, db)` | Set item volume |
301| `set_item_fade_in(track, item, length)` | Set fade-in |
302| `set_item_fade_out(track, item, length)` | Set fade-out |
303| `select_all_items()` | Select all items |
304| `unselect_all_items()` | Deselect all items |
305| `get_selected_items()` | Get selected items |
306| `copy_selected_items()` | Copy to clipboard |
307| `paste_items()` | Paste from clipboard |
308 
309### Markers & Regions (8 tools)
310 
311| Tool | Description |
312|------|-------------|
313| `add_marker(pos, name, color)` | Add marker |
314| `add_region(start, end, name, color)` | Add region |
315| `get_markers()` | Get all markers |
316| `get_regions()` | Get all regions |
317| `delete_marker(index)` | Delete marker |
318| `delete_region(index)` | Delete region |
319| `go_to_marker(index)` | Jump to marker |
320| `go_to_region(index)` | Jump to region start |
321 
322### Automation (8 tools)
323 
324| Tool | Description |
325|------|-------------|
326| `get_track_envelope(track, name)` | Get envelope by name |
327| `get_envelope_point_count(track, name)` | Count envelope points |
328| `add_envelope_point(track, name, time, value, shape)` | Add automation point |
329| `get_envelope_points(track, name)` | Get all points |
330| `delete_envelope_point(track, name, index)` | Delete point |
331| `clear_envelope(track, name)` | Clear all points |
332| `set_track_automation_mode(track, mode)` | Set automation mode |
333| `arm_track_envelope(track, name, arm)` | Arm envelope for recording |
334 
335### Selection & Editing (11 tools)
336 
337| Tool | Description |
338|------|-------------|
339| `undo()` | Undo last action |
340| `redo()` | Redo last undone action |
341| `get_undo_state()` | Get undo/redo state |
342| `select_track(index, exclusive)` | Select a track |
343| `select_all_tracks()` | Select all tracks |
344| `unselect_all_tracks()` | Deselect all tracks |
345| `get_selected_tracks()` | Get selected track indices |
346| `set_time_selection(start, end)` | Set time selection |
347| `get_time_selection()` | Get time selection |
348| `clear_time_selection()` | Clear time selection |
349| `delete_selected_items()` | Delete selected items |
350 
351### Mixing Helpers (6 tools)
352 
353| Tool | Description |
354|------|-------------|
355| `add_mastering_chain()` | Add EQ→Comp→EQ→Limiter to master |
356| `add_parallel_compression(track, db)` | Set up NY compression |
357| `create_bus(name, tracks)` | Create submix bus |
358| `add_eq(track)` | Add ReaEQ |
359| `add_compressor(track)` | Add ReaComp |
360| `add_limiter(track)` | Add ReaLimit |
361 
362### Advanced (4 tools)
363 
364| Tool | Description |
365|------|-------------|
366| `run_action(action_id)` | Run REAPER action by ID |
367| `run_action_by_name(name)` | Run action by name |
368| `get_track_fx_chunk(track, fx)` | Get raw FX state data |
369| `cut_selected_items()` | Cut items to clipboard |
370 
371## Track Indexing
372 
373- **Regular tracks:** 0-based index (first track = 0)
374- **Master track:** Use index `-1`
375 
376```
377"Set the master track volume to -3dB"  → track_index = -1
378"Mute track 1"                          → track_index = 1 (second track)
379```
380 
381## Common Plugin Names
382 
383Use these names with `track_fx_add_by_name()`:
384 
385| Plugin | Name |
386|--------|------|
387| EQ | `ReaEQ` |
388| Compressor | `ReaComp` |
389| Limiter | `ReaLimit` |
390| Gate | `ReaGate` |
391| Delay | `ReaDelay` |
392| Reverb | `ReaVerbate` or `ReaVerb` |
393 
394Third-party plugins use their full name as shown in REAPER's FX browser.
395 
396## Troubleshooting
397 
398### "Cannot connect to REAPER"
3991. Ensure REAPER is running
4002. Ensure the bridge script is running (check REAPER's console)
4013. For file mode: verify the bridge directory exists
4024. For HTTP mode: check port 9000 isn't blocked
403 
404### "Track not found"
405- Track indices are 0-based
406- Use `-1` for master track
407- Check track count with `get_track_count()`
408 
409### Bridge script won't load
410- **Lua:** Ensure LuaSocket is installed (ReaPack → "sockmonkey")
411- **Python:** Enable Python in REAPER preferences
412 
413### Slow response
414- File-based mode has ~50ms latency per call
415- Batch operations when possible (e.g., `add_midi_notes_batch`)
416 
417## Environment Variables
418 
419| Variable | Default | Description |
420|----------|---------|-------------|
421| `REAPER_COMM_MODE` | `file` | Communication mode (`file` or `http`) |
422| `REAPER_BRIDGE_DIR` | `%APPDATA%\REAPER\Scripts\mcp_bridge_data` | File bridge directory |
423| `REAPER_HOST` | `localhost` | HTTP bridge host |
424| `REAPER_PORT` | `9000` | HTTP bridge port |
425 
426## License
427 
428MIT License - see [LICENSE](LICENSE)
429 
430---
431 
432**TwelveTake Studios LLC**
433Website: [twelvetake.com](https://twelvetake.com)
434Contact: contact@twelvetake.com
435