Total Reaper Mcp

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:

``bash ./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\\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\\AppData\Roaming\REAPER\Scripts\
• macOS Scripts folder: ~/Library/Application Support/REAPER/Scripts/

1. The script appears in the action list — select it and click Run
2. Check the REAPER console (View → Show REAPER console) for: "REAPER MCP Bridge (File-based, Full API) started"

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
• On macOS 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. Connect to Claude Code (or other MCP client)

Claude Code (claude mcp add):

# macOS / Linux
claude mcp add reaper-mcp -- /path/to/.venv/bin/python -m server.app

# Windows — must set REAPER_MCP_BRIDGE_DIR explicitly (default path is macOS-only)
claude mcp add reaper-mcp \
  -e REAPER_MCP_BRIDGE_DIR="C:/Users//AppData/Roaming/REAPER/Scripts/mcp_bridge_data" \
  -- C:/path/to/.venv/Scripts/python.exe -m server.app

If you already added the server without the env variable, edit ~/.claude.json and add it to the "env" field:

"reaper-mcp": {
  "type": "stdio",
  "command": "C:/Users//github/total-reaper-mcp/.venv/Scripts/python.exe",
  "args": ["-m", "server.app"],
  "env": {
    "REAPER_MCP_BRIDGE_DIR": "C:/Users//AppData/Roaming/REAPER/Scripts/mcp_bridge_data"
  }
}

4. Verify the setup

1. Check REAPER console shows: "REAPER MCP Bridge (File-based, Full API) started"
2. Check Python server shows: "Server ready. Waiting for connections..."
3. The server will display which profile is active and how many tools were registered
4. The bridge uses file-based communication via:

• macOS: ~/Library/Application Support/REAPER/Scripts/mcp_bridge_data/
• Windows: %APPDATA%\REAPER\Scripts\mcp_bridge_data\

> Windows gotcha: The Python server defaults to the macOS bridge path. Without setting > REAPER_MCP_BRIDGE_DIR, all tool calls will time out even if REAPER and the Lua bridge are running.

Testing

Make sure you have:

1. REAPER running with mcp_bridge.lua loaded (macOS: mcp_bridge_file_v2.lua)
2. 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](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 [IMPLEMENTATIONMASTER.md](IMPLEMENTATIONMASTER.md).

Communication Flow

File-based (Recommended):

1. MCP Client → MCP Server (stdio)
2. MCP Server → REAPER Lua Bridge (via JSON files)
3. Lua Bridge executes REAPER API call
4. Lua Bridge → MCP Server (via JSON files)
5. MCP Server → MCP Client (stdio)

Socket-based:

1. MCP Client → MCP Server (stdio)
2. MCP Server → REAPER Lua Bridge (UDP port 9000)
3. Lua Bridge executes REAPER API call
4. Lua Bridge → MCP Server (UDP port 9001)
5. 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 [IMPLEMENTATIONMASTER.md](IMPLEMENTATIONMASTER.md) for details on which methods are currently implemented.

Contributing

When adding new ReaScript methods:

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

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: shiehn
• Source: shiehn/total-reaper-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.