REAPER MCP Server

An MCP (Model Context Protocol) server that exposes REAPER DAW functionality through a clean API interface.

Platform Support

This project is developed and tested on macOS but should work on Windows and Linux with minimal adaptation, as REAPER provides consistent cross-platform support.

Requirements

• REAPER 6.83+ (includes embedded Lua 5.4 and full ReaScript API)
• Python 3.10+ (required for MCP 1.1.2+)
• LuaSocket library (optional - only needed for socket-based communication)

Architecture

This project uses a hybrid Lua-Python approach:

• Lua Bridge: Runs inside REAPER, handles API calls using REAPER's built-in Lua interpreter
• Python MCP Server: Provides the MCP interface, communicates with REAPER via file-based IPC

The communication flow:

1. MCP client sends request → Python server
2. Python server writes JSON file → Bridge directory
3. Lua bridge reads file → Executes REAPER API
4. Lua bridge writes response → Bridge directory
5. Python server reads response → Returns to MCP client

Quick Start

For AI/LLM Integration (Recommended)

# Start with default profile (dsl-production: 53 tools)
# Includes natural language DSL + essential production tools
python -m server.app

# Or choose a specific profile:
python -m server.app --profile dsl              # Minimal natural language only (15 tools)
python -m server.app --profile groq-essential   # Traditional ReaScript tools (146 tools)
python -m server.app --profile full             # All tools (600+ tools)

The default dsl-production profile is optimized for AI/LLM use, providing natural language commands plus essential MIDI, FX, and rendering tools.

Quick Install (macOS)

./scripts/install.sh

This will:

• Install the Lua bridge to REAPER's Scripts folder
• Configure REAPER to load the bridge on startup
• Set up Python virtual environment
• Create launch scripts
• Optionally set up auto-start on login

Note: The quick install script is macOS-only. Windows users must follow the manual setup below.

Manual Setup

1. Install Python dependencies

macOS / Linux:

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Windows (recommended — using uv):

uv venv --python 3.11
source .venv/Scripts/activate   # Git Bash
# or: .venv\Scripts\activate.bat  (CMD) / .venv\Scripts\Activate.ps1 (PowerShell)
uv pip install -e .

Windows (standard venv):

python -m venv .venv
.venv\Scripts\activate.bat      # CMD
# or: .venv\Scripts\Activate.ps1  (PowerShell)
pip install -e .

2. Set up the bridge

Currently, only the file-based bridge is fully implemented and tested. The socket-based bridge exists but lacks a corresponding server implementation.

Bridge Setup

The MCP server communicates with REAPER through a file-based bridge. This requires no additional dependencies and is the most reliable method.

macOS / Linux:

1. Install the bridge:

   ./scripts/install_bridge.sh
   

Windows:

The install script is macOS-only. Copy the bridge manually:

# Git Bash
cp lua/mcp_bridge.lua "$APPDATA/REAPER/Scripts/"

Or in PowerShell:

Copy-Item lua\mcp_bridge.lua "$env:APPDATA\REAPER\Scripts\"

The bridge is copied as mcp_bridge.lua. REAPER's Scripts folder is typically: C:\Users\<you>\AppData\Roaming\REAPER\Scripts\

Load the bridge in REAPER (all platforms):

1. Open REAPER
2. Go to Actions → Show action list
3. Click the New action button
4. Select Load ReaScript... from the options that appear
5. Navigate to your Scripts folder and select mcp_bridge.lua (Windows) or mcp_bridge_file_v2.lua (macOS)
   • Windows Scripts folder: C:\Users\<you>\AppData\Roaming\REAPER\Scripts\
   • macOS Scripts folder: `~/Library/Application Supp

... View full README on GitHub