Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/shiehn--total-reaper-mcp/badge.svg)](/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

i

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)

  1. # REAPER MCP Server
  2. An MCP (Model Context Protocol) server that exposes [REAPER DAW](https://www.reaper.fm/) functionality through a clean API interface.
  3. ![REAPER MCP Server](assets/repo-readme-image.png)
  4. ## Platform Support
  5. 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.
  6. ## Requirements
  7. - [REAPER](https://www.reaper.fm/) 6.83+ (includes embedded Lua 5.4 and full ReaScript API)
  8. - Python 3.10+ (required for MCP 1.1.2+)
  9. - LuaSocket library (optional - only needed for socket-based communication)
  10. ## Architecture
  11. This project uses a hybrid Lua-Python approach:
  12. - **Lua Bridge**: Runs inside REAPER, handles API calls using REAPER's built-in Lua interpreter
  13. - **Python MCP Server**: Provides the MCP interface, communicates with REAPER via file-based IPC
  14. The communication flow:
  15. 1. MCP client sends request → Python server
  16. 2. Python server writes JSON file → Bridge directory
  17. 3. Lua bridge reads file → Executes REAPER API
  18. 4. Lua bridge writes response → Bridge directory
  19. 5. Python server reads response → Returns to MCP client
  20. ## Quick Start
  21. ### For AI/LLM Integration (Recommended)
  22. ```bash
  23. # Start with default profile (dsl-production: 53 tools)
  24. # Includes natural language DSL + essential production tools
  25. python -m server.app
  26. # Or choose a specific profile:
  27. python -m server.app --profile dsl # Minimal natural language only (15 tools)
  28. python -m server.app --profile groq-essential # Traditional ReaScript tools (146 tools)
  29. python -m server.app --profile full # All tools (600+ tools)
  30. ```
  31. The default `dsl-production` profile is optimized for AI/LLM use, providing natural language commands plus essential MIDI, FX, and rendering tools.
  32. ### Quick Install (macOS)
  33. ```bash
  34. ./scripts/install.sh
  35. ```
  36. This will:
  37. - Install the Lua bridge to REAPER's Scripts folder
  38. - Configure REAPER to load the bridge on startup
  39. - Set up Python virtual environment
  40. - Create launch scripts
  41. - Optionally set up auto-start on login
  42. **Note:** The quick install script is macOS-only. Windows users must follow the manual setup below.
  43. ## Manual Setup
  44. ### 1. Install Python dependencies
  45. **macOS / Linux:**
  46. ```bash
  47. python3 -m venv .venv
  48. source .venv/bin/activate
  49. pip install -e .
  50. ```
  51. **Windows (recommended — using [uv](https://github.com/astral-sh/uv)):**
  52. ```bash
  53. uv venv --python 3.11
  54. source .venv/Scripts/activate # Git Bash
  55. # or: .venv\Scripts\activate.bat (CMD) / .venv\Scripts\Activate.ps1 (PowerShell)
  56. uv pip install -e .
  57. ```
  58. **Windows (standard venv):**
  59. ```bash
  60. python -m venv .venv
  61. .venv\Scripts\activate.bat # CMD
  62. # or: .venv\Scripts\Activate.ps1 (PowerShell)
  63. pip install -e .
  64. ```
  65. ### 2. Set up the bridge
  66. Currently, only the **file-based bridge** is fully implemented and tested. The socket-based bridge exists but lacks a corresponding server implementation.
  67. #### Bridge Setup
  68. The MCP server communicates with REAPER through a file-based bridge. This requires no additional dependencies and is the most reliable method.
  69. **macOS / Linux:**
  70. 1. Install the bridge:
  71. ```bash
  72. ./scripts/install_bridge.sh
  73. ```
  74. **Windows:**
  75. The install script is macOS-only. Copy the bridge manually:
  76. ```bash
  77. # Git Bash
  78. cp lua/mcp_bridge.lua "$APPDATA/REAPER/Scripts/"
  79. ```
  80. Or in PowerShell:
  81. ```powershell
  82. Copy-Item lua\mcp_bridge.lua "$env:APPDATA\REAPER\Scripts\"
  83. ```
  84. The bridge is copied as `mcp_bridge.lua`. REAPER's Scripts folder is typically:
  85. `C:\Users\<you>\AppData\Roaming\REAPER\Scripts\`
  86. **Load the bridge in REAPER (all platforms):**
  87. 1. Open REAPER
  88. 2. Go to **Actions → Show action list**
  89. 3. Click the **New action** button
  90. 4. Select **Load ReaScript...** from the options that appear
  91. 5. Navigate to your Scripts folder and select `mcp_bridge.lua` (Windows) or `mcp_bridge_file_v2.lua` (macOS)
  92. - Windows Scripts folder: `C:\Users\<you>\AppData\Roaming\REAPER\Scripts\`
  93. - macOS Scripts folder: `~/Library/Application Support/REAPER/Scripts/`
  94. 6. The script appears in the action list — select it and click **Run**
  95. 7. Check the REAPER console (**View → Show REAPER console**) for: `"REAPER MCP Bridge (File-based, Full API) started"`
  96. **Start the MCP server:**
  97. ```bash
  98. # Default profile (dsl-production: 53 tools with natural language interface)
  99. python -m server.app
  100. # Or with a specific profile
  101. python -m server.app --profile dsl # Natural language tools only (15 tools)
  102. python -m server.app --profile full # All tools (600+ tools)
  103. ```
  104. **Important Architecture Note:**
  105. - There is only ONE bridge script (`lua/mcp_bridge.lua`) that supports ALL profiles
  106. - The bridge includes both traditional ReaScript functions (600+) and DSL functions
  107. - Profile selection happens in the Python MCP server, NOT in the bridge
  108. - On macOS the bridge is installed as `mcp_bridge_file_v2.lua` for backward compatibility
  109. #### Socket-based Bridge (Not Currently Implemented)
  110. 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.
  111. ### 3. Connect to Claude Code (or other MCP client)
  112. **Claude Code (`claude mcp add`):**
  113. ```bash
  114. # macOS / Linux
  115. claude mcp add reaper-mcp -- /path/to/.venv/bin/python -m server.app
  116. # Windows — must set REAPER_MCP_BRIDGE_DIR explicitly (default path is macOS-only)
  117. claude mcp add reaper-mcp \
  118. -e REAPER_MCP_BRIDGE_DIR="C:/Users/<you>/AppData/Roaming/REAPER/Scripts/mcp_bridge_data" \
  119. -- C:/path/to/.venv/Scripts/python.exe -m server.app
  120. ```
  121. If you already added the server without the env variable, edit `~/.claude.json` and add it to the `"env"` field:
  122. ```json
  123. "reaper-mcp": {
  124. "type": "stdio",
  125. "command": "C:/Users/<you>/github/total-reaper-mcp/.venv/Scripts/python.exe",
  126. "args": ["-m", "server.app"],
  127. "env": {
  128. "REAPER_MCP_BRIDGE_DIR": "C:/Users/<you>/AppData/Roaming/REAPER/Scripts/mcp_bridge_data"
  129. }
  130. }
  131. ```
  132. ### 4. Verify the setup
  133. 1. Check REAPER console shows: "REAPER MCP Bridge (File-based, Full API) started"
  134. 2. Check Python server shows: "Server ready. Waiting for connections..."
  135. 3. The server will display which profile is active and how many tools were registered
  136. 4. The bridge uses file-based communication via:
  137. - **macOS:** `~/Library/Application Support/REAPER/Scripts/mcp_bridge_data/`
  138. - **Windows:** `%APPDATA%\REAPER\Scripts\mcp_bridge_data\`
  139. > **Windows gotcha:** The Python server defaults to the macOS bridge path. Without setting
  140. > `REAPER_MCP_BRIDGE_DIR`, all tool calls will time out even if REAPER and the Lua bridge are running.
  141. ## Testing
  142. Make sure you have:
  143. 1. REAPER running with `mcp_bridge.lua` loaded (macOS: `mcp_bridge_file_v2.lua`)
  144. 2. The MCP server running (`python -m server.app`)
  145. Then run the tests:
  146. ```bash
  147. pytest tests/ -v
  148. ```
  149. To test specific profiles:
  150. ```bash
  151. # Test DSL tools
  152. MCP_TEST_PROFILE=dsl pytest tests/test_dsl_minimal.py -v
  153. # Test with a different profile
  154. MCP_TEST_PROFILE=mixing pytest tests/test_integration.py -v
  155. ```
  156. **Note:** Some tests may fail due to timing issues or minor output format differences. The core functionality has been verified to work correctly.
  157. For integration tests specifically:
  158. ```bash
  159. pytest tests/test_integration.py -v
  160. ```
  161. ### Natural Language Testing
  162. 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.
  163. #### Basic NLP Tests
  164. ```bash
  165. # From the reaper-chat directory
  166. cd reaper-chat
  167. node test-nlp-mcp-mapping.js
  168. ```
  169. This runs tests to verify that natural language inputs correctly map to MCP tools.
  170. #### Enhanced NLP Tests with Conversation Tracking
  171. For comprehensive testing with quality evaluation and improvement tracking:
  172. ```bash
  173. # Ensure you have an OpenAI API key set
  174. export OPENAI_API_KEY=your-api-key-here
  175. # Run enhanced tests with conversation tracking
  176. node test-nlp-with-tracking.js
  177. ```
  178. This advanced test suite:
  179. - Executes actual REAPER commands through MCP
  180. - Evaluates response quality on multiple dimensions
  181. - Tracks all conversations for pattern analysis
  182. - Generates actionable improvement reports
  183. See [reaper-chat/RUN-TRACKED-TESTS.md](reaper-chat/RUN-TRACKED-TESTS.md) for detailed information on:
  184. - Running the enhanced test suite
  185. - Understanding quality metrics
  186. - Using conversation tracking for continuous improvement
  187. - Implementing suggested improvements
  188. The conversation tracking system creates detailed reports in `reaper-chat/conversation-tracking/` that help identify:
  189. - Common failure patterns
  190. - Specific queries that need improvement
  191. - Progress tracking between test sessions
  192. ## Tool Profiles
  193. 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.
  194. ### Available Profiles
  195. | Profile | Tool Count | Description | Use Case |
  196. |---------|------------|-------------|----------|
  197. | `dsl-production` | ~53 | DSL + essential tools | **DEFAULT** - Natural language + core production |
  198. | `dsl` | **15** | Natural language DSL tools | Minimal AI-friendly interface |
  199. | `groq-essential` | ~146 | Core REAPER functionality | Traditional tools, Groq-compatible |
  200. | `groq-extended` | ~200+ | Extended functionality | More tools, may exceed Groq's limit |
  201. | `minimal` | ~100 | Bare minimum tools | Testing and lightweight operations |
  202. | `midi-production` | ~150 | MIDI-focused tools | MIDI composition and editing workflows |
  203. | `mixing` | ~120 | Mixing and mastering tools | Audio mixing, effects, and routing |
  204. | `full` | 600+ | All available tools | Complete access (may overwhelm LLMs) |
  205. ### Using Profiles
  206. ```bash
  207. # List all available profiles
  208. python -m server.app --list-profiles
  209. # Start with default profile (dsl-production)
  210. python -m server.app
  211. # Start with a specific profile
  212. python -m server.app --profile dsl # Minimal natural language (15 tools)
  213. python -m server.app --profile groq-essential # Traditional ReaScript interface
  214. python -m server.app --profile mixing # Mixing-focused tools
  215. python -m server.app --profile full # All 600+ tools
  216. # Using with the relay script
  217. python run_with_relay.py # Uses default (dsl-production)
  218. python run_with_relay.py --profile dsl # Minimal DSL profile
  219. ```
  220. ### DSL (Natural Language) Features
  221. The DSL tools (included in the default `dsl-production` profile) provide a natural language friendly interface that understands flexible inputs:
  222. - **Track references**: "bass", "drums", "track 3", "last track"
  223. - **Volume formats**: "-6dB", "+3", "50%"
  224. - **Time references**: "8 bars", "cursor", "selection"
  225. - **Pan formats**: "L50", "R30", "center"
  226. Example DSL usage:
  227. ```python
  228. # Instead of complex ReaScript calls:
  229. await dsl_track_create(name="Bass", role="bass")
  230. await dsl_track_volume(track="bass", volume="-6dB")
  231. await dsl_loop_create(track="bass", time="8 bars")
  232. ```
  233. ### Creating Custom Profiles
  234. Add your own profile in `server/tool_profiles.py`:
  235. ```python
  236. "my-workflow": {
  237. "name": "My Custom Workflow",
  238. "description": "Tools for my specific needs",
  239. "categories": [
  240. "DSL", # Natural language tools
  241. "Tracks", # Track management
  242. "MIDI", # MIDI operations
  243. "FX", # Effects
  244. ]
  245. }
  246. ```
  247. ## Available Tools
  248. 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).
  249. ### Core DAW Functions
  250. - Track Management & Controls
  251. - Media Items & Takes
  252. - MIDI Operations
  253. - Effects/FX Management
  254. - Automation & Envelopes
  255. - Project Management
  256. - Transport & Playback
  257. ### Music Production Tools
  258. - **Loop & Time Selection Management** - Loop points, time selection, grid quantization
  259. - **Bounce & Render Operations** - Track bouncing, freezing, stem export
  260. - **Groove & Quantization** - Humanization, swing, polyrhythms, tempo detection
  261. - **Bus Routing & Mixing** - Submixes, parallel compression, sidechain routing
  262. ### Advanced Features
  263. - Audio Analysis & Peak Detection
  264. - Video & Visual Media Support
  265. - Color Management
  266. - Layout & Screenset Management
  267. - Script Extension Support
  268. - And much more
  269. For the complete list of all implemented methods, see [IMPLEMENTATION_MASTER.md](IMPLEMENTATION_MASTER.md).
  270. ## Communication Flow
  271. ### File-based (Recommended):
  272. 1. MCP Client → MCP Server (stdio)
  273. 2. MCP Server → REAPER Lua Bridge (via JSON files)
  274. 3. Lua Bridge executes REAPER API call
  275. 4. Lua Bridge → MCP Server (via JSON files)
  276. 5. MCP Server → MCP Client (stdio)
  277. ### Socket-based:
  278. 1. MCP Client → MCP Server (stdio)
  279. 2. MCP Server → REAPER Lua Bridge (UDP port 9000)
  280. 3. Lua Bridge executes REAPER API call
  281. 4. Lua Bridge → MCP Server (UDP port 9001)
  282. 5. MCP Server → MCP Client (stdio)
  283. ## Uninstall
  284. ```bash
  285. ./scripts/uninstall.sh
  286. ```
  287. ## About REAPER
  288. [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.
  289. ## API Reference
  290. 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:
  291. - Track management and routing
  292. - Media items and takes
  293. - MIDI editing
  294. - Envelopes and automation
  295. - Effects and plugins
  296. - Project management
  297. - Transport control
  298. - And much more
  299. See [IMPLEMENTATION_MASTER.md](IMPLEMENTATION_MASTER.md) for details on which methods are currently implemented.
  300. ## Contributing
  301. When adding new ReaScript methods:
  302. 1. Check the implementation checklist in IMPLEMENTATION_MASTER.md
  303. 2. Follow the existing patterns in the codebase
  304. 3. Include tests for all new methods
  305. 4. Update the implementation master list

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.