Skip to content
Back to search

Reaper-MCP

AI-powered music production and post-production in REAPER via MCP — 181 tools for composition, mixing, mastering, batch editing, audio QC, and ReaScript automation.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/xDarkzx/Reaper-MCP with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/xDarkzx/Reaper-MCP'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/xdarkzx--reaper-mcp/badge.svg)](/listings/xdarkzx--reaper-mcp)

HTML

<a href="/listings/xdarkzx--reaper-mcp"><img src="/api/listings/xdarkzx--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.

1. Get ReaperMCP

**Option A:** Click the green **Code** button above → **Download ZIP** → extract to a folder — works with nothing pre-installed, easiest on a brand new machine.

**Option B:** Clone with git (lets you `git pull` for updates later):

A fresh Windows install doesn't ship with git — check first:

git --version

If that says "not recognized", install it, then close and reopen your terminal:

winget install --id Git.Git -e --source winget

(`winget` itself ships with Windows 11 and up-to-date Windows 10. If `winget` isn't found either, grab the installer directly from [git-scm.com](https://git-scm.com/download/win).)

macOS/Linux almost always have git already — `git --version` to check, or `brew install git` / `sudo apt install git` if not.

git clone https://github.com/xDarkzx/Reaper-MCP.git

**Option C:** Already have Python? Install the published package straight from PyPI:

pip install xdarkzx-reaper-mcp

This gives you the `reaper-mcp` command directly — but you'll still need `reaper_scripts/reaper_mcp_server.lua` for Step 3 below, since that one file isn't bundled into the PyPI package (grab it from the repo, or [download it directly](https://github.com/xDarkzx/Reaper-MCP/raw/main/reaper_scripts/reaper_mcp_server.lua)).

2. Run the installer

**Windows:** either double-click `install.bat` in File Explorer, or — if you're already in a terminal from the `git clone` step above — just keep going in the same PowerShell/Command Prompt window:

cd Reaper-MCP
.\install.bat

**macOS / Linux:**

cd Reaper-MCP
bash install.sh

> The installer installs `reaper-mcp` locally and optionally **configures Claude Desktop** — no manual JSON editing needed.

<details> <summary>Manual install / other MCP clients (Cursor, Claude Code, etc.)</summary>

Install manually with `pip install -e .` from the repo folder (or `pip install xdarkzx-reaper-mcp` from PyPI) and add to your client's MCP config:

{
  "mcpServers": {
    "reaper": {
      "command": "reaper-mcp"
    }
  }
}

Check your client's MCP documentation for the config file location.

</details>

3. Load the Lua script in REAPER

**Used the one-click installer?** Already done — it sets up REAPER to auto-load the script on every launch. Just open (or restart) REAPER.

**Manual install?**

1. Open **REAPER** 2. Go to **Actions → Show action list** 3. Click **Load ReaScript...** 4. Navigate to `reaper_scripts/reaper_mcp_server.lua` and select it 5. Click **Run**

> This only loads it for the current session — you'll need to re-run it each time REAPER restarts. See [docs/INSTALLATION.md](docs/INSTALLATION.md) for the auto-start setup.

4. Start producing

Open your AI client and start talking:

"Create 4 tracks: strings, brass, piano, and drums"
"Compose an 8-bar orchestral string arrangement in D minor"
"Add ReaEQ to the piano track and cut the low end below 200Hz"
"Set the tempo to 90 BPM and loop the first 8 bars"

> **REAPER must be open with the Lua script running.** ReaperMCP communicates through file-based IPC — it can't launch REAPER for you.

> See the full [Installation Guide](docs/INSTALLATION.md) for detailed setup on all platforms and MCP clients.

---

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 · 473 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <!-- mcp-name: io.github.xDarkzx/reaper-mcp -->
  2. <h1 align="center">ReaperMCP</h1>
  3. <p align="center">
  4. <strong>AI-powered music production in REAPER through the Model Context Protocol</strong>
  5. </p>
  6. <p align="center">
  7. <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.10+-blue.svg" alt="Python 3.10+" /></a>
  8. <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-green.svg" alt="License" /></a>
  9. <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-purple.svg" alt="MCP Compatible" /></a>
  10. <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/version-0.8.3-orange.svg" alt="v0.8.3" /></a>
  11. <a href="https://github.com/xDarkzx/Reaper-MCP/actions/workflows/ci.yml"><img src="https://github.com/xDarkzx/Reaper-MCP/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
  12. <a href="https://www.reaper.fm/"><img src="https://img.shields.io/badge/REAPER-7%2B-red.svg" alt="REAPER 7+" /></a>
  13. <a href="https://discord.gg/BGn8Ujh37m"><img src="https://img.shields.io/discord/1530363483701510154?label=discord&logo=discord&color=5865F2" alt="Discord" /></a>
  14. <a href="https://github.com/sponsors/xDarkzx"><img src="https://img.shields.io/badge/Sponsor-30363D?logo=githubsponsors&logoColor=EA4AAA" alt="Sponsor" /></a>
  15. </p>
  16. <p align="center">
  17. <a href="#quick-start">Quick Start</a> &bull;
  18. <a href="#why-reapermcp">Why ReaperMCP?</a> &bull;
  19. <a href="#features">Features</a> &bull;
  20. <a href="docs/TOOLS.md">Tools Reference</a> &bull;
  21. <a href="docs/ARCHITECTURE.md">Architecture</a> &bull;
  22. <a href="CHANGELOG.md">Changelog</a> &bull;
  23. <a href="CONTRIBUTING.md">Contributing</a> &bull;
  24. <a href="#troubleshooting">Troubleshooting</a>
  25. </p>
  26. ---
  27. ReaperMCP connects any MCP-compatible AI assistant to [REAPER](https://www.reaper.fm/), giving it full control over music production. Talk to your AI assistant and it composes, mixes, masters, and *measures* your music in real-time — the AI chooses every note, rhythm, and CC itself.
  28. **181 tools across 26 modules** cover the full workflow: MIDI composition and patterns, a vocal-chop pipeline, FX and automatic genre-tuned mixing/mastering (35 style profiles), sends and routing, and post-production QC — batch editing, ReaScript automation, silence/click detection.
  29. **No cloud. Nothing leaves your machine.** ReaperMCP runs entirely locally through a file-based Lua IPC bridge inside REAPER — your project, audio, and MIDI stay on your computer. Bring whatever AI client you already use (Claude Desktop, Claude Code, Cursor, any MCP client) — ReaperMCP handles REAPER.
  30. **If this is useful to you, a star helps other people find it** — that's the whole marketing budget for this project. Want to help keep it maintained? Click the **Sponsor** badge up top.
  31. ### Demo
  32. [![Watch the demo](https://img.youtube.com/vi/F0i5njHaMXQ/hqdefault.jpg)](https://youtu.be/F0i5njHaMXQ)
  33. ### Works With
  34. ReaperMCP works with any AI client that supports the [Model Context Protocol](https://modelcontextprotocol.io):
  35. - [Claude Desktop](https://claude.ai/download) — Anthropic's desktop app
  36. - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) — CLI agent
  37. - [Cursor](https://www.cursor.com/) — AI code editor with MCP support
  38. - [LM Studio](https://lmstudio.ai/) — run local models with MCP tool access
  39. - Any other [MCP-compatible client](https://modelcontextprotocol.io/clients)
  40. ---
  41. ## Why ReaperMCP?
  42. - **Deep control, not just playback.** Most AI-audio integrations expose basic transport — play, stop, record. ReaperMCP exposes REAPER's actual production surface: genre-aware automatic mixing/mastering across 35 style profiles, a vocal-chop pipeline, drum-pattern and chord-progression shorthand, and post-production QC. The AI can produce a track end-to-end, not just push buttons on one you already made.
  43. - **100% local.** No cloud calls, no API keys, nothing leaves your machine — REAPER and the AI talk over a file-based bridge on disk, not a server you don't control.
  44. - **Actively maintained.** CI runs the full test suite across 3 OS × 4 Python versions on every change. Issues get read, discussed, and shipped — not just filed and forgotten.
  45. - **Composable with companion tools.** Pairs with [SongForge-MCP](https://github.com/xDarkzx/SongForge-MCP) (local AI music/vocal generation) and [Audacity-MCP](https://github.com/xDarkzx/Audacity-MCP) (audio cleanup, mastering, and local transcription) — generate, produce, and clean up without leaving the same AI conversation.
  46. ---
  47. ## Quick Start
  48. ### 1. Get ReaperMCP
  49. **Option A:** Click the green **Code** button above → **Download ZIP** → extract to a folder — works with nothing pre-installed, easiest on a brand new machine.
  50. **Option B:** Clone with git (lets you `git pull` for updates later):
  51. A fresh Windows install doesn't ship with git — check first:
  52. ```powershell
  53. git --version
  54. ```
  55. If that says "not recognized", install it, then close and reopen your terminal:
  56. ```powershell
  57. winget install --id Git.Git -e --source winget
  58. ```
  59. (`winget` itself ships with Windows 11 and up-to-date Windows 10. If `winget` isn't found either, grab the installer directly from [git-scm.com](https://git-scm.com/download/win).)
  60. macOS/Linux almost always have git already — `git --version` to check, or `brew install git` / `sudo apt install git` if not.
  61. ```bash
  62. git clone https://github.com/xDarkzx/Reaper-MCP.git
  63. ```
  64. **Option C:** Already have Python? Install the published package straight from PyPI:
  65. ```bash
  66. pip install xdarkzx-reaper-mcp
  67. ```
  68. This gives you the `reaper-mcp` command directly — but you'll still need
  69. `reaper_scripts/reaper_mcp_server.lua` for Step 3 below, since that one
  70. file isn't bundled into the PyPI package (grab it from the repo, or
  71. [download it directly](https://github.com/xDarkzx/Reaper-MCP/raw/main/reaper_scripts/reaper_mcp_server.lua)).
  72. ### 2. Run the installer
  73. **Windows:** either double-click `install.bat` in File Explorer, or — if you're already in a terminal from the `git clone` step above — just keep going in the same PowerShell/Command Prompt window:
  74. ```powershell
  75. cd Reaper-MCP
  76. .\install.bat
  77. ```
  78. **macOS / Linux:**
  79. ```bash
  80. cd Reaper-MCP
  81. bash install.sh
  82. ```
  83. > The installer installs `reaper-mcp` locally and optionally **configures Claude Desktop** — no manual JSON editing needed.
  84. <details>
  85. <summary>Manual install / other MCP clients (Cursor, Claude Code, etc.)</summary>
  86. Install manually with `pip install -e .` from the repo folder (or `pip install xdarkzx-reaper-mcp` from PyPI) and add to your client's MCP config:
  87. ```json
  88. {
  89. "mcpServers": {
  90. "reaper": {
  91. "command": "reaper-mcp"
  92. }
  93. }
  94. }
  95. ```
  96. Check your client's MCP documentation for the config file location.
  97. </details>
  98. ### 3. Load the Lua script in REAPER
  99. **Used the one-click installer?** Already done — it sets up REAPER to auto-load the script on every launch. Just open (or restart) REAPER.
  100. **Manual install?**
  101. 1. Open **REAPER**
  102. 2. Go to **Actions → Show action list**
  103. 3. Click **Load ReaScript...**
  104. 4. Navigate to `reaper_scripts/reaper_mcp_server.lua` and select it
  105. 5. Click **Run**
  106. > This only loads it for the current session — you'll need to re-run it each time REAPER restarts. See [docs/INSTALLATION.md](docs/INSTALLATION.md) for the auto-start setup.
  107. ### 4. Start producing
  108. Open your AI client and start talking:
  109. ```
  110. "Create 4 tracks: strings, brass, piano, and drums"
  111. "Compose an 8-bar orchestral string arrangement in D minor"
  112. "Add ReaEQ to the piano track and cut the low end below 200Hz"
  113. "Set the tempo to 90 BPM and loop the first 8 bars"
  114. ```
  115. > **REAPER must be open with the Lua script running.** ReaperMCP communicates through file-based IPC — it can't launch REAPER for you.
  116. > See the full [Installation Guide](docs/INSTALLATION.md) for detailed setup on all platforms and MCP clients.
  117. ---
  118. ## Features
  119. ### 181 Tools Across 26 Modules
  120. | Category | Tools | Highlights |
  121. |----------|------:|------------|
  122. | **Transport** | 11 | Play, stop, pause, record, set BPM, time signature, playrate, toggle repeat/metronome |
  123. | **Tracks** | 18 | Create, delete, rename, volume, pan, mute, solo, arm, colour, input, folder, mixer state, peak meter, freeze/unfreeze |
  124. | **Track Templates** | 4 | Save, apply, list, and delete REAPER track templates |
  125. | **Project** | 19 | New, open, save, save-as, backup, export audio (WAV/MP3/OGG/FLAC/AIFF), undo/redo (by count, or a whole tool run), notes, grid, render metadata (`project_get/set_metadata`), Notes-tab Title/Author (`project_get/set_notes_info`), `project_get_overview` (change count + info in one call) |
  126. | **Items** | 14 | Get/select/split/delete/move items, set length/volume/mute/fade, insert media, create MIDI, move to track, `items_apply` (batch edits) |
  127. | **Takes** | 4 | List, add, delete, and switch active take |
  128. | **MIDI** | 15 | Insert notes (single/batch), edit/delete notes, insert/delete CC, Program Change/Bank Select (`midi_insert_program_change`), read program names (`midi_list_programs`), count events, note names, sort, set extents (CC reading intentionally omitted — see below) |
  129. | **MIDI Quantize / Humanize** | 3 | `midi_quantize`, `midi_humanize`, `project_set_ripple_mode` |
  130. | **Markers & Regions** | 7 | Add markers/regions, delete, edit, navigate, `markers_apply` (batch marker edits) |
  131. | **Tempo Map** | 4 | Add/delete/list tempo markers, clear all |
  132. | **Envelopes** | 3 | Read, write, and clear automation envelopes (track / item / FX-param) |
  133. | **Selection** | 9 | Time selection, loop points, select/deselect all items/tracks, get selected |
  134. | **Sends & Routing** | 8 | Create/remove sends (with optional MIDI channel routing), set volume/pan/mute, `send_set_midi_channel`, full routing diagram |
  135. | **FX** | 15 | Add/remove plugins, get/set parameters, presets (verified, not a silent no-op), enable/disable, show UI, find instrument, move within chain, rename display label |
  136. | **FX Inventory** | 2 | `fx_list_installed` (detects FabFilter / Waves / iZotope / Valhalla / racks), `set_fx_preferences` |
  137. | **Mix & Master** | 3 | `engine_mix`, `engine_master`, `engine_fix_mix` — 35 style profiles across EDM / Rock / Pop / Electronic / Jazz / Orchestral / Funk-Soul |
  138. | **Sidechain** | 1 | `setup_sidechain` — pin-mapped kick→bass/pad pumping with a single amount dial |
  139. | **Bus Pipelines** | 4 | `setup_parallel_compression`, `setup_drum_bus`, `setup_vocal_chain`, `bounce_stems` |
  140. | **Composition Utility** | 3 | `get_track_instruments`, `analyze_score`, `compose_arrangement` (small batch insert) |
  141. | **Composition Editing** | 9 | `wipe_all_midi`, `reset_composition`, `configure_tracks`, `setup_routing`, `add_markers_batch`, `rewrite_cc`, `edit_section`, `setup_fx_chain`, `setup_effect_bus` |
  142. | **Patterns** | 2 | `create_drum_pattern` (multi-lane step-sequencer notation), `create_chord_progression` (parses `"Cm7, Fm7, Bb7, Eb"` into voiced MIDI) |
  143. | **Loop Library** | 3 | `scan_audio_folder` (parse BPM / key / role from filenames), `detect_common_bpm`, `load_loops` (batch-create tracks + load stems). Point at a sample-pack folder and the AI builds a track from it. |
  144. | **Vocal Chops** | 10 | **`chop_pipeline`** — end-to-end: reorders slices from the source vocal onto a NEW track with style-specific rhythms (chillstep / future bass / porter / trap), pitches to chord tones, stutters + harmonises + fades. **Primitives:** `item_split_at_transients`, `item_split_at_positions`, `take_set_pitch`, `take_set_playrate`, `take_set_reversed`, `item_duplicate`. **Helpers:** `analyze_chop_set`, `arrange_chops_to_chord_tones`, `stack_chop_layers`. |
  145. | **Audio Analysis** | 7 | `analyze_loudness` (LUFS vs. streaming/broadcast/cinema target), `analyze_clipping`, `analyze_silence`, `analyze_peaks`, `analyze_region_qc` (edit-oriented QC — silence/click candidates per region), `analyze_frequency_spectrum`, `analyze_stereo_field`. Optional extras: `pip install -e ".[analysis]"` (or `pip install "xdarkzx-reaper-mcp[analysis]"` if installed from PyPI) |
  146. | **Script** | 2 | `script_list`, `script_run` — discover and execute ReaScript files in the project's Scripts tree |
  147. | **Demo** | 1 | `demo_edm_project` — one-shot full-project demo render (smoke test + reference) |
  148. > See **[docs/TOOLS.md](docs/TOOLS.md)** for the complete tool reference with every signature and a one-line description for each tool.
  149. ### Tool profiles
  150. The default 181-tool surface is designed for full-featured frontier models. Smaller/cheaper models (Groq Llama 3 caps at 128 tools, some local models lower still) will silently truncate. Set `REAPER_MCP_PROFILE` in your client's server config to pick a workflow-specific subset:
  151. | Profile | Tools | For |
  152. |---------|------:|-----|
  153. | `full` *(default)* | ~180 | Frontier models — Claude, GPT-4, Gemini |
  154. | `composition` | ~130 | Writing / editing music (includes patterns, loops, batch item/marker edits, ReaScript) |
  155. | `mixing` | ~71 | Mixing, mastering, bus pipelines |
  156. | `analysis` | ~53 | Inspect + measure only |
  157. | `minimal` | ~43 | Smoke test / basic control |
  158. ```json
  159. {
  160. "mcpServers": {
  161. "reaper": {
  162. "command": "reaper-mcp",
  163. "env": { "REAPER_MCP_PROFILE": "mixing" }
  164. }
  165. }
  166. }
  167. ```
  168. ### Mixing & Mastering Pipelines
  169. 35 professional style profiles drive automatic EQ, compression, reverb buses, sidechain pumping, and mastering — each tuned to industry-standard LUFS targets and character.
  170. | Tool | What It Does |
  171. |------|-------------|
  172. | `engine_mix(style)` | Per-track EQ + compression + reverb buses with send routing. Auto-detects FabFilter Pro-Q 3 / Pro-C 2 / Pro-R or falls back to REAPER stock (ReaEQ / ReaComp / ReaVerbate) |
  173. | `engine_master(style)` | Master-bus chain: HP 25 Hz → bus glue comp → tonal shelf EQ → stereo width → brick-wall limiter, targeting style-specific LUFS and true-peak ceilings |
  174. | `engine_fix_mix(style)` | Non-destructive repair pass — re-runs the mix pipeline on an existing session, preserving user tweaks where possible |
  175. | `setup_sidechain(source, target, amount)` | Kick → bass / pad pumping via channels 3/4 + pin-mapped sidechain inputs |
  176. | `setup_drum_bus / setup_parallel_compression / setup_vocal_chain` | Ready-made bus recipes for drums, parallel (NY) comp, and pro vocal chains |
  177. | `bounce_stems(track_indices)` | Render selected tracks individually to WAV stems |
  178. **Styles (35):**
  179. - **EDM (11):** `melodic_dubstep`, `big_room`, `future_bass`, `future_house`, `deep_house`, `tech_house`, `progressive_house`, `dubstep`, `trap`, `drum_and_bass`, `trance`
  180. - **Rock (6):** `alt_rock`, `classic_rock`, `pop_rock`, `hard_rock`, `punk`, `post_rock`
  181. - **Pop (4):** `modern_pop`, `dance_pop`, `indie_pop`, `rnb_pop`
  182. - **Electronic (4):** `synthwave`, `lofi`, `ambient`, `hiphop`
  183. - **Jazz (3):** `swing_jazz`, `jazz_fusion`, `latin_jazz`
  184. - **Orchestral (3):** `classical_chamber`, `cinematic_trailer`, `ambient_orchestral`
  185. - **Funk/Soul (4):** `classic_funk`, `motown_soul`, `neo_soul`, `disco_funk`
  186. **Smart plugin detection.** `fx_list_installed()` inspects what's on the user's machine and reports the best-available EQ / compressor / reverb / limiter / de-esser / gate / saturator / multiband / stereo tool — covering FabFilter, Waves, iZotope, Valhalla, Softube, TDR, Slate, Melda, Soundtoys, Airwindows, REAPER stock, and common rack hosts (Waves StudioRack, Blue Cat PatchWork, Kilohearts Snap Heap). Users can pin category → plugin preferences via `set_fx_preferences(...)`.
  187. ### AI-Driven Composition
  188. The AI writes every note, rhythm, CC curve, and keyswitch itself using the granular MIDI and FX tools above. A single `00_core.md` instruction file provides the tool surface, shorthand notation, BBC Spitfire CC reference, and per-family mixing tips. Voicing, humanization, structure, and genre conventions all come from the AI's own musical knowledge.
  189. ---
  190. ## Works well alongside SongForge-MCP
  191. Need vocals or a full backing track and don't want to record or license anything? [SongForge-MCP](https://github.com/xDarkzx/SongForge-MCP) is a companion MCP server that generates original vocal + instrumental tracks locally (powered by ACE-Step 1.5 — no cloud service, no subscription, no account) and can split out an isolated vocal stem. Run both servers in the same Claude Desktop session: generate the track there, then import, arrange, and produce it further here without leaving the conversation.
  192. ---
  193. ## Architecture
  194. ```
  195. ┌──────────────┐ stdio ┌──────────────┐ file IPC ┌──────────────┐
  196. │ MCP Client │◄──────────────►│ ReaperMCP │◄────────────►│ REAPER │
  197. │(AI assistant)│ (JSON-RPC) │ FastMCP │ (JSON files) │ (Lua script)│
  198. └──────────────┘ └──────────────┘ └──────────────┘
  199. ```
  200. The Python server writes commands to `command.json` in a shared temp directory; a Lua script inside REAPER polls, executes, and writes results to `response.json`. No sockets, no ports, no network exposure.
  201. **IPC directory:**
  202. - Windows: `%TEMP%\reaper_mcp`
  203. - macOS: `$TMPDIR/reaper_mcp`
  204. - Linux: `/tmp/reaper_mcp`
  205. ### Key design decisions
  206. - **File-based IPC** — no port allocation, no firewall surface.
  207. - **Static Lua dispatch** — every handler is explicit code, no `load` / `dofile` / `loadstring`.
  208. - **Dynamic tool registration** — drop a module into `reaper_mcp/tools/`, export `register(mcp)`, and it's picked up automatically.
  209. - **Heartbeat + timeouts** — the client detects a stale REAPER (no lock-file update) and raises a typed error instead of hanging.
  210. - **Conservative per-call limits** — `MAX_COMPOSE_TRACKS`, `MAX_TOTAL_NOTES_PER_CALL` etc. keep any single command under ~2 s of REAPER's main thread time.
  211. > Full details — IPC protocol, request lifecycle, registration internals, mix-engine pipeline, style catalog — in **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)**.
  212. ### Project structure
  213. ```
  214. Reaper-MCP/
  215. ├── reaper_mcp/
  216. │ ├── main.py # FastMCP server entry (`reaper-mcp` command)
  217. │ ├── tool_registry.py # Auto-discovers tool modules
  218. │ ├── reaper_client.py # File-IPC client (lock, heartbeat, timeouts)
  219. │ ├── cc_map.py # CC number translation helpers
  220. │ ├── shorthand.py # Compact composition notation parser
  221. │ ├── instructions/
  222. │ │ └── 00_core.md # System-prompt instructions injected into MCP
  223. │ ├── mix_engine/ # Mixing + mastering pipelines
  224. │ │ ├── __init__.py # run_mix_pipeline
  225. │ │ ├── master.py # run_master_pipeline
  226. │ │ ├── fix_mix.py # Non-destructive mix repair
  227. │ │ ├── detect.py # FabFilter / REAPER stock detection
  228. │ │ ├── fx_inventory.py # Installed-plugin discovery
  229. │ │ ├── plugins.py # Plugin param translation
  230. │ │ ├── profiles.py # Legacy orchestral profiles
  231. │ │ ├── profiles_v2.py # Schema for 35 style profiles
  232. │ │ └── catalog/ # Per-family style catalog
  233. │ │ ├── edm.py # 11 EDM subgenres
  234. │ │ ├── rock.py # 6 rock subgenres
  235. │ │ ├── pop.py # 4 pop subgenres
  236. │ │ ├── electronic.py # synthwave, lofi, ambient, hiphop
  237. │ │ └── _shared.py # Shared role → EQ/comp library
  238. │ └── tools/ # 26 modules, 181 auto-registered tools
  239. │ ├── transport_tools.py # Playback and recording (11)
  240. │ ├── track_tools.py # Track management + freeze (18)
  241. │ ├── template_tools.py # Track templates (4)
  242. │ ├── project_tools.py # Project/file operations + metadata (18)
  243. │ ├── item_tools.py # Media item management + batch apply (14)
  244. │ ├── take_tools.py # Takes (4)
  245. │ ├── midi_tools.py # MIDI notes, CC, program change (15)
  246. │ ├── quantize_tools.py # Quantize / humanize / ripple (3)
  247. │ ├── marker_tools.py # Markers, regions + batch apply (7)
  248. │ ├── tempo_tools.py # Tempo map markers (4)
  249. │ ├── envelope_tools.py # Automation envelopes (3)
  250. │ ├── selection_tools.py # Selection and loop (9)
  251. │ ├── send_tools.py # Sends and routing (8)
  252. │ ├── fx_tools.py # FX chain + params (15)
  253. │ ├── inventory_tools.py # fx_list_installed + set_fx_preferences (2)
  254. │ ├── mix_tools.py # engine_mix / engine_master / engine_fix_mix (3)
  255. │ ├── sidechain_tools.py # setup_sidechain (1)
  256. │ ├── pipeline_tools.py # Drum bus, parallel comp, vocal chain, stems (4)
  257. │ ├── compose_tools.py # get_track_instruments, analyze_score, compose_arrangement (3)
  258. │ ├── compose_edit_tools.py # wipe_all_midi, edit_section, rewrite_cc, … (9)
  259. │ ├── patterns_tools.py # create_drum_pattern, create_chord_progression (2)
  260. │ ├── loops_tools.py # scan_audio_folder, detect_common_bpm, load_loops (3)
  261. │ ├── chops_tools.py # Vocal chop pipeline + primitives (10)
  262. │ ├── analysis_tools.py # LUFS, clipping, spectrum, stereo field, silence/peak/region QC (7, optional deps)
  263. │ ├── script_tools.py # ReaScript discovery + execution (2)
  264. │ ├── demo_tools.py # demo_edm_project (1)
  265. │ └── compose_helpers.py # Shared helpers (no tools)
  266. ├── reaper_mcp_shared/
  267. │ ├── constants.py # IPC paths, timeouts, safety limits
  268. │ ├── error_codes.py # ReaperMCPError + ErrorCode enum
  269. │ └── protocol.py # Command / response formatting
  270. ├── reaper_scripts/
  271. │ └── reaper_mcp_server.lua # Lua IPC bridge (runs inside REAPER)
  272. ├── docs/
  273. │ ├── INSTALLATION.md # Detailed setup for all platforms
  274. │ ├── PROJECT_SETUP.md # Template setups for orchestral / pop / EDM
  275. │ ├── TOOLS.md # Complete tool reference
  276. │ └── ARCHITECTURE.md # IPC protocol, mix engine, design notes
  277. ├── tests/
  278. ├── install.bat / install.sh # One-click installers
  279. ├── CHANGELOG.md
  280. ├── CONTRIBUTING.md
  281. ├── LICENSE
  282. └── pyproject.toml
  283. ```
  284. ---
  285. ## Setting Up Your REAPER Project
  286. ReaperMCP controls REAPER — but **you need instruments loaded** for the AI to compose with. The AI can create tracks and write MIDI, but it can't browse or install VST plugins for you.
  287. ### Before You Start Composing
  288. 1. **Open REAPER** and create a new project
  289. 2. **Add tracks** with your desired VST instruments (Kontakt, Spitfire, LABS, etc.)
  290. 3. **Load patches** — e.g., "Violin 1 Legato", "French Horn a4", "Grand Piano"
  291. 4. **Save as a template** (File → Save Project As Template) so you don't repeat this every time
  292. The AI will use `get_track_instruments` to detect what's loaded and compose for those instruments automatically.
  293. > See the full **[Project Setup Guide](docs/PROJECT_SETUP.md)** for recommended instrument templates (orchestral, pop/rock, EDM) and what plugins to load.
  294. **Known limitation — multi-sample/one-shot instruments:** the AI can't see which sound is mapped to which key inside a plugin's own sample browser, or whether a given key is a one-shot vs. a held/sustained sample — that's private plugin state no host can read, true of most sample-based VSTs/AUs, not specific to this project. See [Project Setup Guide § multi-sample libraries](docs/PROJECT_SETUP.md#known-limitation-multi-sample-libraries) for the workaround.
  295. ---
  296. ## Troubleshooting
  297. | Problem | Fix |
  298. |---------|-----|
  299. | "No response from REAPER" | Make sure REAPER is open and the Lua script is running. Go to Actions → Show action list → find `reaper_mcp_server.lua` → Run. |
  300. | Script not found in Actions | Click **Load ReaScript...** first to register it, then Run. |
  301. | "Connection timeout" | REAPER is busy. Wait for it to finish, or check if the Lua script crashed (re-run it). |
  302. | Works once then stops | The Lua script may have stopped. Re-run it from Actions. |
  303. | Claude Desktop doesn't see ReaperMCP | Restart Claude Desktop after editing the config. Check `%APPDATA%\Claude\claude_desktop_config.json` (Windows) or `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS). |
  304. | "command not found: reaper-mcp" | Run the installer again, or manually: `pip install -e .` from the repo folder, or `pip install xdarkzx-reaper-mcp`. |
  305. | MIDI notes sound robotic | Make sure your AI is using the humanization instructions — ask it to "humanize the MIDI" or "add expression CC curves". |
  306. ---
  307. ## Development
  308. ```bash
  309. # Install dev dependencies
  310. pip install -e ".[dev]"
  311. # Run tests
  312. pytest tests/ -x -q
  313. # Run lint (real bugs + security patterns, not style/formatting)
  314. ruff check .
  315. ```
  316. ### Adding New Tools
  317. 1. Create a module in `reaper_mcp/tools/` (or add to an existing one)
  318. 2. Export a `register(mcp: FastMCP)` function
  319. 3. Define your tools with `@mcp.tool()` decorators
  320. 4. That's it — the tool registry auto-discovers it on startup
  321. See [CONTRIBUTING.md](CONTRIBUTING.md) for full guidelines.
  322. ---
  323. ## Community
  324. Turning this into a tool every REAPER user reaches for takes more than one person. If you're using ReaperMCP — even just trying it out — come join the Discord: share what you built, report what's broken, suggest what's missing, or just hang out with other people doing AI-driven production. Communities grow one person telling another this exists, so if you know someone who'd get value out of this, send them the link.
  325. <p align="center">
  326. <a href="https://discord.gg/BGn8Ujh37m">
  327. <img src="https://img.shields.io/badge/Join_the_Discord-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="Join the Discord" />
  328. </a>
  329. </p>
  330. ---
  331. ## Support
  332. If ReaperMCP has helped with your music production, consider sponsoring:
  333. <p align="center">
  334. <a href="https://github.com/sponsors/xDarkzx">
  335. <img src="https://img.shields.io/badge/Sponsor-30363D?style=for-the-badge&logo=githubsponsors&logoColor=EA4AAA" alt="GitHub Sponsors" />
  336. </a>
  337. </p>
  338. Your support helps keep this project maintained and free for everyone.
  339. ---
  340. ## Hiring / Consulting
  341. Need a custom MCP server, a native plugin/IPC integration, or a local AI pipeline built for your product? This repo and its sibling projects — [Audacity-MCP](https://github.com/xDarkzx/Audacity-MCP), [SongForge-MCP](https://github.com/xDarkzx/SongForge-MCP) — are public, working examples of exactly that. Open to contract work: **dkstudiosnz@gmail.com**.
  342. ---
  343. ## Documentation
  344. - **[Installation Guide](docs/INSTALLATION.md)** — Detailed setup for Windows, macOS, Linux and every supported MCP client
  345. - **[Project Setup Guide](docs/PROJECT_SETUP.md)** — Setting up your REAPER project with instruments for AI composition
  346. - **[Tools Reference](docs/TOOLS.md)** — Every tool grouped by domain, with a one-line description and signature
  347. - **[Architecture](docs/ARCHITECTURE.md)** — IPC protocol, Lua bridge, dynamic tool registration, mix-engine pipeline, style catalog
  348. - **[Contributing](CONTRIBUTING.md)** — How to add tools and contribute
  349. - **[Changelog](CHANGELOG.md)** — Version history and release notes
  350. **Want to know when a new version ships?** Click **Watch → Custom → Releases** at the top of this repo — GitHub notifies you on every tagged [Release](../../releases), without the noise of every commit or issue.
  351. ## License
  352. Apache License 2.0 — see [LICENSE](LICENSE) for details.
  353. Built by [Daniel Hodgetts](https://github.com/xDarkzx) &bull; [𝕏 @daehonz1](https://x.com/daehonz1)
  354. ---
  355. Need a custom tool, plugin, or integration built like this? I take on select engineering projects — come find me on the [Discord](https://discord.gg/BGn8Ujh37m) and leave a message, or open an issue here.

Ratings and comments

Sign in to rate this skill.

Sign in

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