ReaperMCP

ReaperMCP connects any MCP-compatible AI assistant to REAPER, 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.

180 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.

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.

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.

Demo

Works With

ReaperMCP works with any AI client that supports the Model Context Protocol:

• Claude Desktop — Anthropic's desktop app

• Claude Code — CLI agent

• Cursor — AI code editor with MCP support

• LM Studio — run local models with MCP tool access

• Any other MCP-compatible client

Why ReaperMCP?

• 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.

• 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.

• 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.

• Composable with companion tools. Pairs with SongForge-MCP (local AI music/vocal generation) and Audacity-MCP (audio cleanup, mastering, and local transcription) — generate, produce, and clean up without leaving the same AI conversation.

Related MCP server: reaper-reapy-mcp

Quick Start

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.)

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).

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.

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.

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 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 for detailed setup on all platforms and MCP clients.

Features

180 Tools Across 26 Modules

See docs/TOOLS.md for the complete tool reference with every signature and a one-line description for each tool.

Tool profiles

The default 180-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:

{
  "mcpServers": {
    "reaper": {
      "command": "reaper-mcp",
      "env": { "REAPER_MCP_PROFILE": "mixing" }
    }
  }
}

Mixing & Mastering Pipelines

35 professional style profiles drive automatic EQ, compression, reverb buses, sidechain pumping, and mastering — each tuned to industry-standard LUFS targets and character.

Styles (35):

• EDM (11): melodic_dubstep, big_room, future_bass, future_house, deep_house, tech_house, progressive_house, dubstep, trap, drum_and_bass, trance

• Rock (6): alt_rock, classic_rock, pop_rock, hard_rock, punk, post_rock

• Pop (4): modern_pop, dance_pop, indie_pop, rnb_pop

• Electronic (4): synthwave, lofi, ambient, hiphop

• Jazz (3): swing_jazz, jazz_fusion, latin_jazz

• Orchestral (3): classical_chamber, cinematic_trailer, ambient_orchestral

• Funk/Soul (4): classic_funk, motown_soul, neo_soul, disco_funk

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(...).

AI-Driven Composition

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.

Works well alongside SongForge-MCP

Need vocals or a full backing track and don't want to record or license anything? 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.

Architecture

┌──────────────┐     stdio      ┌──────────────┐   file IPC    ┌──────────────┐
│  MCP Client  │◄──────────────►│  ReaperMCP   │◄────────────►│    REAPER    │
│(AI assistant)│    (JSON-RPC)  │   FastMCP    │  (JSON files) │  (Lua script)│
└──────────────┘                └──────────────┘               └──────────────┘

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.

IPC directory:

• Windows: %TEMP%\reaper_mcp

• macOS: $TMPDIR/reaper_mcp

• Linux: /tmp/reaper_mcp

Key design decisions

• File-based IPC — no port allocation, no firewall surface.

• Static Lua dispatch — every handler is explicit code, no load / dofile / loadstring.

• Dynamic tool registration — drop a module into reaper_mcp/tools/, export register(mcp), and it's picked up automatically.

• Heartbeat + timeouts — the client detects a stale REAPER (no lock-file update) and raises a typed error instead of hanging.

• 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.

Full details — IPC protocol, request lifecycle, registration internals, mix-engine pipeline, style catalog — in docs/ARCHITECTURE.md.

Project structure

Reaper-MCP/
├── reaper_mcp/
│   ├── main.py                     # FastMCP server entry (`reaper-mcp` command)
│   ├── tool_registry.py            # Auto-discovers tool modules
│   ├── reaper_client.py            # File-IPC client (lock, heartbeat, timeouts)
│   ├── cc_map.py                   # CC number translation helpers
│   ├── shorthand.py                # Compact composition notation parser
│   ├── instructions/
│   │   └── 00_core.md              # System-prompt instructions injected into MCP
│   ├── mix_engine/                 # Mixing + mastering pipelines
│   │   ├── __init__.py             # run_mix_pipeline
│   │   ├── master.py               # run_master_pipeline
│   │   ├── fix_mix.py              # Non-destructive mix repair
│   │   ├── detect.py               # FabFilter / REAPER stock detection
│   │   ├── fx_inventory.py         # Installed-plugin discovery
│   │   ├── plugins.py              # Plugin param translation
│   │   ├── profiles.py             # Legacy orchestral profiles
│   │   ├── profiles_v2.py          # Schema for 35 style profiles
│   │   └── catalog/                # Per-family style catalog
│   │       ├── edm.py              # 11 EDM subgenres
│   │       ├── rock.py             # 6 rock subgenres
│   │       ├── pop.py              # 4 pop subgenres
│   │       ├── electronic.py       # synthwave, lofi, ambient, hiphop
│   │       └── _shared.py          # Shared role → EQ/comp library
│   └── tools/                      # 26 modules, 180 auto-registered tools
│       ├── transport_tools.py      # Playback and recording (11)
│       ├── track_tools.py          # Track management + freeze (18)
│       ├── template_tools.py       # Track templates (4)
│       ├── project_tools.py        # Project/file operations + metadata (18)
│       ├── item_tools.py           # Media item management + batch apply (14)
│       ├── take_tools.py           # Takes (4)
│       ├── midi_tools.py           # MIDI notes, CC, program change (15)
│       ├── quantize_tools.py       # Quantize / humanize / ripple (3)
│       ├── marker_tools.py         # Markers, regions + batch apply (7)
│       ├── tempo_tools.py          # Tempo map markers (4)
│       ├── envelope_tools.py       # Automation envelopes (3)
│       ├── selection_tools.py      # Selection and loop (9)
│       ├── send_tools.py           # Sends and routing (8)
│       ├── fx_tools.py             # FX chain + params (15)
│       ├── inventory_tools.py      # fx_list_installed + set_fx_preferences (2)
│       ├── mix_tools.py            # engine_mix / engine_master / engine_fix_mix (3)
│       ├── sidechain_tools.py      # setup_sidechain (1)
│       ├── pipeline_tools.py       # Drum bus, parallel comp, vocal chain, stems (4)
│       ├── compose_tools.py        # get_track_instruments, analyze_score, compose_arrangement (3)
│       ├── compose_edit_tools.py   # wipe_all_midi, edit_section, rewrite_cc, … (9)
│       ├── patterns_tools.py       # create_drum_pattern, create_chord_progression (2)
│       ├── loops_tools.py          # scan_audio_folder, detect_common_bpm, load_loops (3)
│       ├── chops_tools.py          # Vocal chop pipeline + primitives (10)
│       ├── analysis_tools.py       # LUFS, clipping, spectrum, stereo field, silence/peak/region QC (7, optional deps)
│       ├── script_tools.py         # ReaScript discovery + execution (2)
│       ├── demo_tools.py           # demo_edm_project (1)
│       └── compose_helpers.py      # Shared helpers (no tools)
├── reaper_mcp_shared/
│   ├── constants.py                # IPC paths, timeouts, safety limits
│   ├── error_codes.py              # ReaperMCPError + ErrorCode enum
│   └── protocol.py                 # Command / response formatting
├── reaper_scripts/
│   └── reaper_mcp_server.lua       # Lua IPC bridge (runs inside REAPER)
├── docs/
│   ├── INSTALLATION.md             # Detailed setup for all platforms
│   ├── PROJECT_SETUP.md            # Template setups for orchestral / pop / EDM
│   ├── TOOLS.md                    # Complete tool reference
│   └── ARCHITECTURE.md             # IPC protocol, mix engine, design notes
├── tests/
├── install.bat / install.sh        # One-click installers
├── CHANGELOG.md
├── CONTRIBUTING.md
├── LICENSE
└── pyproject.toml

Setting Up Your REAPER Project

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.

Before You Start Composing

1. Open REAPER and create a new project

2. Add tracks with your desired VST instruments (Kontakt, Spitfire, LABS, etc.)

3. Load patches — e.g., "Violin 1 Legato", "French Horn a4", "Grand Piano"

4. Save as a template (File → Save Project As Template) so you don't repeat this every time

The AI will use get_track_instruments to detect what's loaded and compose for those instruments automatically.

See the full Project Setup Guide for recommended instrument templates (orchestral, pop/rock, EDM) and what plugins to load.

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 for the workaround.

Troubleshooting

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -x -q

# Run lint (real bugs + security patterns, not style/formatting)
ruff check .

Adding New Tools

1. Create a module in reaper_mcp/tools/ (or add to an existing one)

2. Export a register(mcp: FastMCP) function

3. Define your tools with @mcp.tool() decorators

4. That's it — the tool registry auto-discovers it on startup

See CONTRIBUTING.md for full guidelines.

Community

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.

Support

If ReaperMCP has helped with your music production, consider sponsoring:

Your support helps keep this project maintained and free for everyone.

Documentation

• Installation Guide — Detailed setup for Windows, macOS, Linux and every supported MCP client

• Project Setup Guide — Setting up your REAPER project with instruments for AI composition

• Tools Reference — Every tool grouped by domain, with a one-line description and signature

• Architecture — IPC protocol, Lua bridge, dynamic tool registration, mix-engine pipeline, style catalog

• Contributing — How to add tools and contribute

• Changelog — Version history and release notes

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, without the noise of every commit or issue.

License

Apache License 2.0 — see LICENSE for details.

Built by Daniel Hodgetts • 𝕏 @daehonz1