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 may reference outdated configurations. For the most reliable setup, follow the manual instructions below.

Manual Setup

1. Install Python dependencies

# Create and activate virtual environment (Python 3.10+ required)
python3.10 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install the package
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.

1. Install the bridge:

   ./scripts/install_bridge.sh
   

2. Load the bridge in REAPER:

   • Open REAPER
   • Go to Actions → Show action list
   • Click "Load..." and select mcp_bridge_file_v2.lua from your Scripts folder
   • Run the action (check the REAPER console for startup message)

3. Start the MCP server:

   # Default profile (dsl-production: 53 tools with natural language interface)
   python -m server.app
   
   # Or with a specific profile
   python -m server.app --profile dsl      # Natural language tools only (15 tools)
   python -m server.app --profile full     # All tools (600+ tools)
   

Important Architecture Note:

• There is only ONE bridge script (lua/mcp_bridge.lua) that supports ALL profiles
• The bridge includes both traditional ReaScript functions (600+) and DSL functions
• Profile selection happens in the Python MCP server, NOT in the bridge
• The bridge is installed as mcp_bridge_file_v2.lua for backward compatibility

Socket-based Bridge (Not Currently Implemented)

While the Lua script lua/mcp_bridge.lua exists for socket-based communication, there is no corresponding Python serve

... View full README on GitHub