reaper-mcp

# TwelveTake REAPER MCP

A [TwelveTake Studios](https://twelvetake.com) project.

[![Tools](https://img.shields.io/badge/tools-177-blue)](https://github.com/TwelveTake-Studios/reaper-mcp)
[![Buy Me a Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-support-yellow)](https://buymeacoffee.com/twelvetake)
[![Ko-fi](https://img.shields.io/badge/Ko--fi-support-ff5e5b)](https://ko-fi.com/twelvetake)

**[Setup guide, examples and FAQ -> twelvetake.com/tools/reaper-mcp](https://twelvetake.com/tools/reaper-mcp/)**

Listed in the [MCP Registry](https://registry.modelcontextprotocol.io/) as `mcp-name: com.twelvetake/reaper-mcp`.

A comprehensive Model Context Protocol (MCP) server that enables AI assistants to control REAPER DAW for mixing, mastering, MIDI composition, and full music production workflows.

**Version:** 1.7.7

## Why This Server

### Workflow Automation, Not Just API Wrappers

Most 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:

| Tool | What it does for you |
|------|---------------------|
| `setup_sidechain_compression()` | Creates send, routes to channels 3-4, configures ReaComp's detector input — complete sidechain setup in one call |
| `add_mastering_chain()` | Adds ReaEQ → ReaComp → ReaEQ → ReaLimit to master track with proper signal flow |
| `add_parallel_compression()` | Creates a bus track, sets up the send, adds compressor — NY-style compression ready to blend |
| `create_bus()` | Creates a submix track and routes your specified tracks to it |
| `get_project_summary()` | Returns track count, all track names/volumes/pans/FX, markers, regions, tempo, time signature — everything your AI needs in one call |

### Zero Configuration

- **File-based communication** works immediately — no network setup, no ports to configure
- **Stock REAPER Lua only** — the bridge script has no dependencies, nothing extra to install in REAPER
- Copy the script, run it, connect your AI assistant

### 177 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, edit, navigate, render by region
- **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 script runs inside REAPER and handles communication with the MCP server.

The package can deploy it for you:

```bash
uvx twelvetake-reaper-mcp --install-bridge
```

That copies `reaper_mcp_bridge.lua` into REAPER's Scripts folder for your platform, backing
up any existing copy 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"`.

To do it by hand instead:

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. In REAPER: **Actions → Show action list → Load ReaScript**
3. Select `reaper_mcp_bridge.lua` and click **Run**

You should see "REAPER MCP Bridge (File-based, Full API) started" in REAPER's console.

### 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`](https://docs.astral.sh/uv/) (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):

```json
{
  "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:

```bash
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:

```bash
pip install -r requirements.txt   # or: pip install mcp
```

Point your MCP client at the local script:

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

Then check the connection with:

```bash
python test_connection.py
```

#### Nix flake (optional)

If you use [Nix](https://nixos.org/), the repo ships a flake-based dev shell that provides
Python 3.12 and creates/activates a virtualenv for you:

```bash
# Enter the dev shell manually
nix develop

# Or, with direnv, auto-activate on cd:
direnv allow
```

Then install the dependencies as usual:

```bash
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:

| Platform | Path |
|----------|------|
| Windows | `%APPDATA%\REAPER\Scripts\mcp_bridge_data` |
| macOS | `~/Library/Application Support/REAPER/Scripts/mcp_bridge_data` |
| Linux | `~/.config/REAPER/Scripts/mcp_bridge_data` (or `~/.reaper/...` for older installs) |

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 (23 tools)

| Tool | Description |
|------|-------------|
| `get_track_count()` | Get total number of tracks (excluding master) |
| `get_track(index)` | Get track info (name, volume, pan, mute, solo) |
| `get_all_tracks()` | Get info for all tracks |
| `get_master_track()` | Get master track info |
| `insert_track(index, name)` | Create a new track |
| `delete_track(index)` | Delete a track |
| `set_track_name(index, name)` | Rename a track |
| `set_track_volume(index, db)` | Set volume in dB |
| `set_track_pan(index, pan)` | Set pan (-1 to 1) |
| `set_track_mute(index, mute)` | Mute/unmute track |
| `set_track_solo(index, solo)` | Solo/unsolo track |
| `set_track_phase(index, invert)` | Invert phase |
| `set_track_width(index, width)` | Set stereo width (0-2) |
| `set_track_color(index, r, g, b)` | Set track color |
| `get_track_peak(index, channel)` | Get current peak level (dB) |
| `get_track_peak_hold(index, channel)` | Get held peak since last reset (dB) |
| `clear_all_peak_indicators()` | Reset peak hold on all tracks |
| `get_track_master_send(index)` | Get master/parent send state |
| `set_track_master_send(index, enabled)` | Enable/disable master send |
| `set_track_as_folder(index, depth)` | Set as folder parent/child |
| `arm_track(index, arm)` | Arm for recording |
| `set_track_input(index, input)` | Set record input |
| `set_track_monitor(index, mode)` | Set monitor mode |

### FX Operations (16 tools)

| Tool | Description |
|------|-------------|
| `track_fx_get_count(index)` | Count FX on track |
| `