total-reaper-mcp
Reaper DAW MCP Server with 100% Reascript Coverage
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/shiehn--total-reaper-mcp)HTML
<a href="/listings/shiehn--total-reaper-mcp"><img src="/api/listings/shiehn--total-reaper-mcp/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
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.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 409 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # REAPER MCP Server
- An MCP (Model Context Protocol) server that exposes [REAPER DAW](https://www.reaper.fm/) 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](https://www.reaper.fm/) 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)
- ```bash
- # 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)
- ```bash
- ./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:**
- ```bash
- python3 -m venv .venv
- source .venv/bin/activate
- pip install -e .
- ```
- **Windows (recommended — using [uv](https://github.com/astral-sh/uv)):**
- ```bash
- 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):**
- ```bash
- 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:
- ```bash
- # Git Bash
- cp lua/mcp_bridge.lua "$APPDATA/REAPER/Scripts/"
- ```
- Or in PowerShell:
- ```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 Support/REAPER/Scripts/`
- 6. The script appears in the action list — select it and click **Run**
- 7. Check the REAPER console (**View → Show REAPER console**) for: `"REAPER MCP Bridge (File-based, Full API) started"`
- **Start the MCP server:**
- ```bash
- # 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`):**
- ```bash
- # 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/<you>/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:
- ```json
- "reaper-mcp": {
- "type": "stdio",
- "command": "C:/Users/<you>/github/total-reaper-mcp/.venv/Scripts/python.exe",
- "args": ["-m", "server.app"],
- "env": {
- "REAPER_MCP_BRIDGE_DIR": "C:/Users/<you>/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:
- ```bash
- pytest tests/ -v
- ```
- To test specific profiles:
- ```bash
- # 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:
- ```bash
- 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
- ```bash
- # 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:
- ```bash
- # 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
- ```bash
- # 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:
- ```python
- # 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`:
- ```python
- "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](IMPLEMENTATION_MASTER.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
- ```bash
- ./scripts/uninstall.sh
- ```
- ## About REAPER
- [REAPER](https://www.reaper.fm/) 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](https://www.reaper.fm/sdk/reascript/reascripthelp.html). 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](IMPLEMENTATION_MASTER.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
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.