REAPER MCP Server

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

REAPER MCP Server

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:

MCP client sends request → Python server
Python server writes JSON file → Bridge directory
Lua bridge reads file → Executes REAPER API
Lua bridge writes response → Bridge directory
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.

Install the bridge:
```
./scripts/install_bridge.sh
```
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)

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 server implementation. The socket bridge requires LuaSocket and would need a server that listens on UDP port 9000.

3. Verify the setup

Check REAPER console shows: "REAPER MCP Bridge (File-based, Full API) started"
Check Python server shows: "Server ready. Waiting for connections..."
The server will display which profile is active and how many tools were registered
The bridge uses file-based communication via ~/Library/Application Support/REAPER/Scripts/mcp_bridge_data/

Testing

Make sure you have:

REAPER running with mcp_bridge_file_v2.lua loaded
The MCP server running (python -m server.app)

Then run the tests:

pytest tests/ -v

To test specific profiles:

# Test DSL tools
MCP_TEST_PROFILE=dsl pytest tests/test_dsl_minimal.py -v

# Test with a different profile
MCP_TEST_PROFILE=mixing pytest tests/test_integration.py -v

Note: Some tests may fail due to timing issues or minor output format differences. The core functionality has been verified to work correctly.

For integration tests specifically:

pytest tests/test_integration.py -v

Natural Language Testing

The REAPER MCP Server includes comprehensive natural language processing (NLP) tests to ensure the system correctly maps user intent to appropriate tools. These tests are particularly important for AI/LLM integration.

Basic NLP Tests

# From the reaper-chat directory
cd reaper-chat
node test-nlp-mcp-mapping.js

This runs tests to verify that natural language inputs correctly map to MCP tools.

Enhanced NLP Tests with Conversation Tracking

For comprehensive testing with quality evaluation and improvement tracking:

# Ensure you have an OpenAI API key set
export OPENAI_API_KEY=your-api-key-here

# Run enhanced tests with conversation tracking
node test-nlp-with-tracking.js

This advanced test suite:

Executes actual REAPER commands through MCP
Evaluates response quality on multiple dimensions
Tracks all conversations for pattern analysis
Generates actionable improvement reports

See reaper-chat/RUN-TRACKED-TESTS.md for detailed information on:

Running the enhanced test suite
Understanding quality metrics
Using conversation tracking for continuous improvement
Implementing suggested improvements

The conversation tracking system creates detailed reports in reaper-chat/conversation-tracking/ that help identify:

Common failure patterns
Specific queries that need improvement
Progress tracking between test sessions

Tool Profiles

The REAPER MCP Server supports tool profiles to limit which tools are exposed based on your needs or LLM limitations. Many LLMs have tool count restrictions (e.g., Groq: 128, OpenAI: 128), and profiles help you stay within these limits while focusing on the tools you need.

Available Profiles

Profile	Tool Count	Description	Use Case
`dsl-production`	~53	DSL + essential tools	DEFAULT - Natural language + core production
`dsl`	15	Natural language DSL tools	Minimal AI-friendly interface
`groq-essential`	~146	Core REAPER functionality	Traditional tools, Groq-compatible
`groq-extended`	~200+	Extended functionality	More tools, may exceed Groq's limit
`minimal`	~100	Bare minimum tools	Testing and lightweight operations
`midi-production`	~150	MIDI-focused tools	MIDI composition and editing workflows
`mixing`	~120	Mixing and mastering tools	Audio mixing, effects, and routing
`full`	600+	All available tools	Complete access (may overwhelm LLMs)

Using Profiles

# List all available profiles
python -m server.app --list-profiles

# Start with default profile (dsl-production)
python -m server.app

# Start with a specific profile
python -m server.app --profile dsl           # Minimal natural language (15 tools)
python -m server.app --profile groq-essential # Traditional ReaScript interface
python -m server.app --profile mixing         # Mixing-focused tools
python -m server.app --profile full           # All 600+ tools

# Using with the relay script
python run_with_relay.py                      # Uses default (dsl-production)
python run_with_relay.py --profile dsl        # Minimal DSL profile

DSL (Natural Language) Features

The DSL tools (included in the default dsl-production profile) provide a natural language friendly interface that understands flexible inputs:

Track references: "bass", "drums", "track 3", "last track"
Volume formats: "-6dB", "+3", "50%"
Time references: "8 bars", "cursor", "selection"
Pan formats: "L50", "R30", "center"

Example DSL usage:

# Instead of complex ReaScript calls:
await dsl_track_create(name="Bass", role="bass")
await dsl_track_volume(track="bass", volume="-6dB")
await dsl_loop_create(track="bass", time="8 bars")

Creating Custom Profiles

Add your own profile in server/tool_profiles.py:

"my-workflow": {
    "name": "My Custom Workflow",
    "description": "Tools for my specific needs",
    "categories": [
        "DSL",          # Natural language tools
        "Tracks",       # Track management
        "MIDI",         # MIDI operations
        "FX",           # Effects
    ]
}

Available Tools

The REAPER MCP Server implements 600+ tools across 40+ categories. The number of tools available depends on the profile you choose (see Tool Profiles section above).

Core DAW Functions

Track Management & Controls
Media Items & Takes
MIDI Operations
Effects/FX Management
Automation & Envelopes
Project Management
Transport & Playback

Music Production Tools

Loop & Time Selection Management - Loop points, time selection, grid quantization
Bounce & Render Operations - Track bouncing, freezing, stem export
Groove & Quantization - Humanization, swing, polyrhythms, tempo detection
Bus Routing & Mixing - Submixes, parallel compression, sidechain routing

Advanced Features

Audio Analysis & Peak Detection
Video & Visual Media Support
Color Management
Layout & Screenset Management
Script Extension Support
And much more

For the complete list of all implemented methods, see IMPLEMENTATION_MASTER.md.

Communication Flow

File-based (Recommended):

MCP Client → MCP Server (stdio)
MCP Server → REAPER Lua Bridge (via JSON files)
Lua Bridge executes REAPER API call
Lua Bridge → MCP Server (via JSON files)
MCP Server → MCP Client (stdio)

Socket-based:

MCP Client → MCP Server (stdio)
MCP Server → REAPER Lua Bridge (UDP port 9000)
Lua Bridge executes REAPER API call
Lua Bridge → MCP Server (UDP port 9001)
MCP Server → MCP Client (stdio)

Uninstall

./scripts/uninstall.sh

About REAPER

REAPER is a complete digital audio production application for computers, offering a full multitrack audio and MIDI recording, editing, processing, mixing and mastering toolset. REAPER supports Windows, macOS, and Linux, providing consistent functionality across all platforms.

API Reference

This project implements a subset of the REAPER ReaScript API. The ReaScript API provides comprehensive control over REAPER's functionality including:

Track management and routing
Media items and takes
MIDI editing
Envelopes and automation
Effects and plugins
Project management
Transport control
And much more

See IMPLEMENTATION_MASTER.md for details on which methods are currently implemented.

Contributing

When adding new ReaScript methods:

Check the implementation checklist in IMPLEMENTATION_MASTER.md
Follow the existing patterns in the codebase
Include tests for all new methods
Update the implementation master list

REAPER MCP Server

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

REAPER MCP Server

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:

MCP client sends request → Python server
Python server writes JSON file → Bridge directory
Lua bridge reads file → Executes REAPER API
Lua bridge writes response → Bridge directory
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.

Install the bridge:
```
./scripts/install_bridge.sh
```
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)

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)

3. Verify the setup

Check REAPER console shows: "REAPER MCP Bridge (File-based, Full API) started"
Check Python server shows: "Server ready. Waiting for connections..."
The server will display which profile is active and how many tools were registered
The bridge uses file-based communication via ~/Library/Application Support/REAPER/Scripts/mcp_bridge_data/

Testing

Make sure you have:

REAPER running with mcp_bridge_file_v2.lua loaded
The MCP server running (python -m server.app)

Then run the tests:

pytest tests/ -v

To test specific profiles:

# Test DSL tools
MCP_TEST_PROFILE=dsl pytest tests/test_dsl_minimal.py -v

# Test with a different profile
MCP_TEST_PROFILE=mixing pytest tests/test_integration.py -v

Note: Some tests may fail due to timing issues or minor output format differences. The core functionality has been verified to work correctly.

For integration tests specifically:

pytest tests/test_integration.py -v

Natural Language Testing

Basic NLP Tests

# From the reaper-chat directory
cd reaper-chat
node test-nlp-mcp-mapping.js

This runs tests to verify that natural language inputs correctly map to MCP tools.

Enhanced NLP Tests with Conversation Tracking

For comprehensive testing with quality evaluation and improvement tracking:

# Ensure you have an OpenAI API key set
export OPENAI_API_KEY=your-api-key-here

# Run enhanced tests with conversation tracking
node test-nlp-with-tracking.js

This advanced test suite:

Executes actual REAPER commands through MCP
Evaluates response quality on multiple dimensions
Tracks all conversations for pattern analysis
Generates actionable improvement reports

See reaper-chat/RUN-TRACKED-TESTS.md for detailed information on:

Running the enhanced test suite
Understanding quality metrics
Using conversation tracking for continuous improvement
Implementing suggested improvements

The conversation tracking system creates detailed reports in reaper-chat/conversation-tracking/ that help identify:

Common failure patterns
Specific queries that need improvement
Progress tracking between test sessions

Tool Profiles

Available Profiles

Profile	Tool Count	Description	Use Case
`dsl-production`	~53	DSL + essential tools	DEFAULT - Natural language + core production
`dsl`	15	Natural language DSL tools	Minimal AI-friendly interface
`groq-essential`	~146	Core REAPER functionality	Traditional tools, Groq-compatible
`groq-extended`	~200+	Extended functionality	More tools, may exceed Groq's limit
`minimal`	~100	Bare minimum tools	Testing and lightweight operations
`midi-production`	~150	MIDI-focused tools	MIDI composition and editing workflows
`mixing`	~120	Mixing and mastering tools	Audio mixing, effects, and routing
`full`	600+	All available tools	Complete access (may overwhelm LLMs)

Using Profiles

# List all available profiles
python -m server.app --list-profiles

# Start with default profile (dsl-production)
python -m server.app

# Start with a specific profile
python -m server.app --profile dsl           # Minimal natural language (15 tools)
python -m server.app --profile groq-essential # Traditional ReaScript interface
python -m server.app --profile mixing         # Mixing-focused tools
python -m server.app --profile full           # All 600+ tools

# Using with the relay script
python run_with_relay.py                      # Uses default (dsl-production)
python run_with_relay.py --profile dsl        # Minimal DSL profile

DSL (Natural Language) Features

The DSL tools (included in the default dsl-production profile) provide a natural language friendly interface that understands flexible inputs:

Track references: "bass", "drums", "track 3", "last track"
Volume formats: "-6dB", "+3", "50%"
Time references: "8 bars", "cursor", "selection"
Pan formats: "L50", "R30", "center"

Example DSL usage:

# Instead of complex ReaScript calls:
await dsl_track_create(name="Bass", role="bass")
await dsl_track_volume(track="bass", volume="-6dB")
await dsl_loop_create(track="bass", time="8 bars")

Creating Custom Profiles

Add your own profile in server/tool_profiles.py:

"my-workflow": {
    "name": "My Custom Workflow",
    "description": "Tools for my specific needs",
    "categories": [
        "DSL",          # Natural language tools
        "Tracks",       # Track management
        "MIDI",         # MIDI operations
        "FX",           # Effects
    ]
}

Available Tools

The REAPER MCP Server implements 600+ tools across 40+ categories. The number of tools available depends on the profile you choose (see Tool Profiles section above).

Core DAW Functions

Track Management & Controls
Media Items & Takes
MIDI Operations
Effects/FX Management
Automation & Envelopes
Project Management
Transport & Playback

Music Production Tools

Loop & Time Selection Management - Loop points, time selection, grid quantization
Bounce & Render Operations - Track bouncing, freezing, stem export
Groove & Quantization - Humanization, swing, polyrhythms, tempo detection
Bus Routing & Mixing - Submixes, parallel compression, sidechain routing

Advanced Features

Audio Analysis & Peak Detection
Video & Visual Media Support
Color Management
Layout & Screenset Management
Script Extension Support
And much more

For the complete list of all implemented methods, see IMPLEMENTATION_MASTER.md.

Communication Flow

File-based (Recommended):

MCP Client → MCP Server (stdio)
MCP Server → REAPER Lua Bridge (via JSON files)
Lua Bridge executes REAPER API call
Lua Bridge → MCP Server (via JSON files)
MCP Server → MCP Client (stdio)

Socket-based:

MCP Client → MCP Server (stdio)
MCP Server → REAPER Lua Bridge (UDP port 9000)
Lua Bridge executes REAPER API call
Lua Bridge → MCP Server (UDP port 9001)
MCP Server → MCP Client (stdio)

Uninstall

./scripts/uninstall.sh

About REAPER

API Reference

This project implements a subset of the REAPER ReaScript API. The ReaScript API provides comprehensive control over REAPER's functionality including:

Track management and routing
Media items and takes
MIDI editing
Envelopes and automation
Effects and plugins
Project management
Transport control
And much more

See IMPLEMENTATION_MASTER.md for details on which methods are currently implemented.

Contributing

When adding new ReaScript methods:

Check the implementation checklist in IMPLEMENTATION_MASTER.md
Follow the existing patterns in the codebase
Include tests for all new methods
Update the implementation master list