ReaperMCP

AI-powered music production in REAPER through the Model Context Protocol

Quick Start • Features • Tools Reference • Architecture • Troubleshooting

ReaperMCP connects any MCP-compatible AI assistant to REAPER, giving it full control over music production through 153 tools across 24 modules — transport, tracks, MIDI, patterns (drum / chord progressions), loop-library pipeline (scan folder → pick by BPM/key → load into REAPER), FX, envelopes, sidechain, mixing, mastering, bus pipelines, and objective audio analysis. 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.

ReaperMCP itself runs entirely on your machine via a file-based Lua IPC bridge inside REAPER — your project, audio, and MIDI never leave your computer. The AI "brain" naturally lives wherever you already run it: Claude Desktop / Claude Code / Cursor / Antigravity / any MCP client. You bring the AI, ReaperMCP handles REAPER.

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
• Any other MCP-compatible client

Features

153 Tools Across 24 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 147-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

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

Styles (25):

• 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

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.

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 25 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/                      # 24 modules, 153 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 (11)
│       ├── item_tools.py           # Media item management (13)
│       ├── take_tools.py           # Takes (4)
│       ├── midi_tools.py           # MIDI notes and CC (13)
│       ├── quantize_tools.py       # Quantize / humanize / ripple (3)
│       ├── marker_tools.py         # Markers and regions (6)
│       ├── 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 (7)
│       ├── fx_tools.py             # FX chain + params (14)
│       ├── 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)
│       ├── analysis_tools.py       # LUFS, clipping, spectrum, stereo field (4, optional deps)
│       ├── 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.

Development

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

# Run tests
pytest tests/ -x -q

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.

Support

If ReaperMCP has helped with your music production, consider buying me a coffee:

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

Quick Start

1. Get ReaperMCP

Option A: Click the green Code button above → Download ZIP → extract to a folder

Option B: Clone with git:

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

2. Run the installer

Open the folder and run:

• Windows: Double-click install.bat
• macOS / Linux: Open terminal in the folder and run bash install.sh

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

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

3. Load the Lua script in REAPER

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

You only need to load the script once — REAPER remembers it. The script must be running for MCP to work.

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.

Troubleshooting

License

Apache License 2.0 — see LICENSE for details.

Built by Daniel Hodgetts • 𝕏 @daehonz1