REAPER MCP

TwelveTake REAPER MCP

A TwelveTake Studios project.

[Tools] [Buy Me a Coffee] [Ko-fi]

Setup guide, examples and FAQ -> twelvetake.com/tools/reaper-mcp

Listed in the MCP Registry as mcp-name: com.twelvetake/reaper-mcp.

TwelveTake REAPER MCP is a Model Context Protocol server that enables AI assistants to control REAPER for mixing, mastering, MIDI composition and music production.

Version: 1.11.0

Why This Server

Workflow tools

In addition to direct control of REAPER, the server includes workflow tools that complete multi-step production tasks in a single call:

Zero Configuration

• File-based communication works immediately — no network setup, no ports to configure
• Stock REAPER only: the bridge is a plain Lua script and the analyzer is a JSFX plugin, so you don't install anything else in REAPER
• Copy the script, run it, connect your AI assistant

188 Tools Covering Real Production Needs

• Full FX control — add/remove plugins, get/set any parameter by index, manage presets, bypass
• FX parameter automation — automate any plugin knob (flanger depth, filter cutoff, etc.)
• Complete routing — sends, receives, sidechain routing to specific channel pairs
• Automation — create envelopes, add/edit points, set automation modes
• MIDI — create items, add notes individually or in batches, edit velocities
• MIDI editing — transpose, quantize with swing, humanize, snap to a scale, stretch, legato, strum, velocity ramps — each targetable by pitch range, beat window, or channel
• Audio items — import, split, duplicate, fade, position, mute
• Markers & regions: create, rename, delete and jump to them
• Session organizing: move tracks and folders, hide tracks from the arrange view or mixer, set track heights, rename takes and set the project playback rate
• Measurement: loudness, loudness range, true peak, the octave-band spectrum and stereo correlation for the master, a track or an item. It passes the EBU's synthetic compliance signals for loudness, true peak and loudness range.
• Undoable edits: every change the AI makes is one named step in REAPER's undo history ("MCP: delete track"), so Ctrl+Z in REAPER reverses one tool call at a time

Requirements

• REAPER (any recent version; full live suite green through REAPER 7.79)
• Python 3.10+ (for the MCP server)
• An MCP-compatible AI assistant

Installation

1. Install the Bridge Script in REAPER

The bridge is a Lua script that runs inside REAPER. The MCP server works on your project through it. Install it one of three ways.

Option A: one command, then run it once in REAPER

uvx twelvetake-reaper-mcp --install-bridge

That copies reaper_mcp_bridge.lua into REAPER's Scripts folder for your platform, and the TwelveTake MCP Analyzer, a JSFX plugin that the measurement tools use, into Effects/TwelveTake. If a different copy of the bridge is already there, it backs that copy up first. It writes nothing else, and the server never touches your REAPER installation on its own. Pass a path if REAPER is portable or installed somewhere unusual: --install-bridge "/path/to/REAPER/Scripts".

Then load it in REAPER. Open Actions → Show action list:

[REAPER's Actions menu with Show action list highlighted]

Click New action → Load ReaScript:

[The action list with the New action menu open and Load ReaScript highlighted]

Select reaper_mcp_bridge.lua in the Scripts folder and click Open:

[The Load Script dialog in REAPER's Scripts folder with reaper_mcp_bridge.lua selected]

The script is now in the action list. Select it and click Run:

[The action list filtered to the bridge script, ready to run]

The bridge runs in the background, without opening a window, until you close REAPER. Step 3 checks that it is working.

Next time, find it by typing mcp bridge in the action list's filter box, or have REAPER start it for you (below).

Option B: ReaPack

If you use ReaPack, open Extensions → ReaPack → Import repositories:

[REAPER's Extensions menu with ReaPack's Import repositories highlighted]

and paste this address:

https://github.com/TwelveTake-Studios/reaper-mcp/raw/main/index.xml

[ReaPack's Import repositories dialog with the address pasted in]

Then open Extensions → ReaPack → Browse packages, find TwelveTake REAPER MCP bridge, right-click it, choose Install, and click OK:

[ReaPack's package browser with Install highlighted for the bridge]

ReaPack adds the script to the action list and installs the analyzer. Run the script from there as in option A.

Option C: by hand

1. Copy reaper_mcp_bridge.lua to your REAPER Scripts folder:
   • Windows: %APPDATA%\REAPER\Scripts\
   • macOS: ~/Library/Application Support/REAPER/Scripts/
   • Linux: ~/.config/REAPER/Scripts/
2. Copy twelvetake_mcp_analyzer.jsfx to Effects/TwelveTake/, next to that Scripts folder. The measurement tools need it; nothing else does.
3. Load and run the script as in option A.

Start the bridge with REAPER

A script stops when REAPER closes. To have REAPER start the bridge every time it launches:

uvx twelvetake-reaper-mcp --install-bridge --autostart

That adds a marked block to __startup.lua in REAPER's Scripts folder, backing the file up first, and leaves anything else in it alone. --remove-autostart takes the block out again. If you installed with ReaPack, run uvx twelvetake-reaper-mcp --autostart instead; it points REAPER at the ReaPack copy.

Updating

From 1.7.8 on, an update needs no step inside REAPER:

uvx twelvetake-reaper-mcp@latest --install-bridge

The running bridge loads the new script by itself, and the command tells you so, for example:

The running bridge reloaded itself: 1.7.8 -> 1.7.9.

With ReaPack, Extensions → ReaPack → Synchronize packages fetches the new script. It runs the next time the bridge starts, or right away with uvx twelvetake-reaper-mcp --reload-bridge. The server also asks a running bridge to reload when the bridge is too old for it.

Updating from 1.7.7 or older needs one last manual step: run the script in REAPER again after installing it.

2. Install and Configure the MCP Server

The server is published on PyPI as twelvetake-reaper-mcp. The simplest path is to let your MCP client launch it with uvx (or pipx) — nothing to install by hand.

Add it to your MCP client's configuration (e.g. .mcp.json, or your client's MCP settings):

{  "mcpServers": {    "reaper": {      "command": "uvx",      "args": ["twelvetake-reaper-mcp"]    }  }}

VS Code uses a top-level servers key with "type": "stdio" instead of mcpServers.

To confirm the server starts on its own:

uvx twelvetake-reaper-mcp# or: pipx run twelvetake-reaper-mcp

It waits quietly for a client to connect — press Ctrl+C to stop.

3. Verify

With REAPER open and the bridge running, ask your assistant "how many tracks are in my project?" — a number back means the server, bridge, and REAPER are all talking.

Run from source (for development)

To work on the server itself, run it from a clone instead of from PyPI. Install the dependencies:

pip install -r requirements.txt   # or: pip install "mcp>=1.2.0,<2.0"

Point your MCP client at the local script:

{  "mcpServers": {    "reaper": {      "command": "python",      "args": ["path/to/reaper_mcp_server.py"]    }  }}

Then check the connection with:

python test_connection.py

Nix flake (optional)

If you use Nix, the repo ships a flake-based dev shell that provides Python 3.12 and creates/activates a virtualenv for you:

# Enter the dev shell manuallynix develop
# Or, with direnv, auto-activate on cd:direnv allow

Then install the dependencies as usual:

pip install -r requirements.txt

This pins the Python version and keeps dependencies isolated from your system.

Note: the x86_64-linux dev shell is tested and working. The macOS (Darwin) shells are provided but have not been tested — confirmation from a macOS user is welcome.

How It Communicates

The server and the bridge exchange JSON files in a mailbox directory that the bridge script polls from inside REAPER. There is no network configuration and no port to open.

MCP Server                    REAPER Bridge    │                              │    ├── writes request_N.json ────►│    │                              ├── processes request    │◄── reads response_N.json ────┤

Bridge directory: REAPER's own Scripts/mcp_bridge_data, resolved per platform:

Override with REAPER_BRIDGE_DIR for portable installs. The server prints the directory it resolved to stderr on startup, and includes it in any timeout error.

The HTTP transport that shipped alongside this was removed in v1.7.2. It had been deprecated since v1.2.1, and its request parser could never read a POST body, so no call it was handed ever reached REAPER. REAPER_COMM_MODE no longer does anything.

Quick Start Examples

Basic Track Operations

"How many tracks are in my project?""Create a new track called 'Vocals'""Set track 0 volume to -6dB""Mute track 2""Solo the drums track"

Mixing

"Add ReaComp to the bass track""Set up sidechain compression from the kick to the bass""Create a drum bus and route tracks 0-3 to it""Add a mastering chain to the master track"

FX and Parameters

"What plugins are on track 0?""Get the parameters for the compressor on track 1""Set the threshold to -20dB""Bypass the EQ on the vocal track"

MIDI Composition

"Create a 4-bar MIDI item on track 0""Add a C major chord at the start""Get all the notes in the MIDI item""Set the velocity of note 0 to 100"

Transport and Navigation

"Play the project""Stop playback""Set the cursor to 30 seconds""Add a marker called 'Chorus' at the current position"

Project Management

"What's the project tempo?""Set the tempo to 120 BPM""Save the project""Render to D:/Output/mix.wav"

Tool Reference

Track Operations (26 tools)

FX Operations (16 tools)

ReaEQ Operations (5 tools)

Dedicated ReaEQ band control using REAPER's EQ-specific API, which handles ReaEQ's non-linear parameter curves (dB gain, log frequency, log Q) correctly.

Take FX Operations (11 tools)

Per-take (per-item) FX, mirroring the track FX tools. Every take is addressed by (track_index, item_index, take_index).

Take Management & Comping (8 tools)

Multi-take workflows: list/switch/delete takes, explode/crop, REAPER 7 fixed-lane comping.

Routing (9 tools)

Transport (12 tools)

Project (15 tools)

MIDI Operations (8 tools)

MIDI Utilities (14 tools)

Editing tools for notes that already exist. Every one takes the same optional filter — a pitch range, an onset window in beats from the item start, and a channel — so you can target a phrase without selecting anything by hand. Timing is in beats, pitch in semitones. Each is one undo step.

remove_overlapping_midi_notes is the only one here that can remove notes; the rest only move what is already there. It is flagged destructive so a client can prompt first.

Audio Items (17 tools)

Markers & Regions (10 tools)

Automation (8 tools)

FX Parameter Automation (5 tools)

Selection & Editing (11 tools)

Measurement (3 tools)

Both measure the master mix unless you give them a track or an item. The loudness figures come from REAPER's own loudness measurement. True peak, the spectrum and the stereo figures come from the TwelveTake MCP Analyzer, which --install-bridge installs and the ReaPack package includes.

Mixing Helpers (6 tools)

Advanced (4 tools)

Track Indexing

• Regular tracks: 0-based index (first track = 0)
• Master track: Use index -1

"Set the master track volume to -3dB"  → track_index = -1"Mute track 1"                          → track_index = 1 (second track)

Common Plugin Names

Use these names with track_fx_add_by_name():

Third-party plugins use their full name as shown in REAPER's FX browser.

Troubleshooting

"Cannot connect to REAPER"

1. Ensure REAPER is running
2. Ensure the bridge script is running: start it from the action list (type mcp bridge in the filter box)
3. Verify the bridge directory exists

"Track not found"

• Track indices are 0-based
• Use -1 for master track
• Check track count with get_track_count()

Bridge script won't load

• Deploy it with twelvetake-reaper-mcp --install-bridge, then load and run it from REAPER's action list. REAPER runs the deployed copy, not the one in a clone.

Slow response

• File-based mode has ~50ms latency per call
• Batch operations when possible (e.g., add_midi_notes_batch)

Environment Variables

Contributing

See CONTRIBUTING.md. Read the first section before writing a patch: this repo is published from a private working repo through an explicit allowlist, so PRs are ported by hand rather than merged, and it is better to know that up front. A well-diagnosed issue is worth as much here as a patch and costs you far less.

Contributors

People outside the project whose work is in this software are listed in CONTRIBUTORS.md, including several whose diagnoses shipped before anyone here thought to look for them.

License

MIT License - see LICENSE

TwelveTake Studios LLC Website: twelvetake.com Contact: [email protected]