Skip to main content
Glama

reaper-mcp-mac

An MCP server that lets an AI assistant drive a live REAPER session on macOS — create tracks, write MIDI, add FX, control transport — in real time.

Claude (MCP client)  ──stdio──►  reaper-mcp-mac (Node/TS)  ──file IPC──►  Lua bridge inside REAPER

Node/TypeScript server + a Lua ReaScript bridge that runs inside REAPER. They talk over file-based IPC (JSON request/response files in a shared folder) — no sockets, no extensions, no LuaSocket. Reliable and dependency-free.

Why this shape

REAPER embeds a native Lua interpreter with the complete ReaScript API, but only inside its own process — Node can't call it directly. So the bridge is Lua (mandatory), and the MCP server is Node (talks to Claude). The two halves exchange atomic JSON files: the server writes request_<id>.json, the Lua defer loop executes it and writes response_<id>.json.

Related MCP server: ReaperMCP

Requirements

  • macOS, REAPER 7.x (developed against 7.79)

  • Node.js 18+ (tested on 24)

Install

cd reaper-mcp
npm install
npm run build

1. Install the Lua bridge into REAPER

./scripts/install_bridge.sh

This copies lua/mcp_bridge.lua to ~/Library/Application Support/REAPER/Scripts/reaper_mcp_bridge.lua and offers to auto-start it on REAPER launch.

2. Start the bridge inside REAPER

  • If you chose auto-start: restart REAPER.

  • Otherwise (or right now, without restarting): in REAPER → Actions → Show action list… → New action… → Load ReaScript… → select Scripts/reaper_mcp_bridge.lua → then select it in the list and click Run.

A ReaScript console appears showing [reaper-mcp-mac] bridge started. The bridge then runs quietly via a defer loop until REAPER closes.

3. Verify the round-trip

npm run smoke

Expected: a _ping with REAPER's version, the project state, and a track count. If it times out, the bridge isn't running inside REAPER (see step 2).

Use with an MCP client

Point your MCP client at the built server. Example (Claude Desktop claude_desktop_config.json):

{
  "mcpServers": {
    "reaper": {
      "command": "node",
      "args": ["/Users/atticus/Documents/code/atticusofsparta/reaper-mcp/dist/index.js"]
    }
  }
}

For Claude Code:

claude mcp add reaper -- node /Users/atticus/Documents/code/atticusofsparta/reaper-mcp/dist/index.js

Skill, helpers and tools

  • skills/reaper/SKILL.md: the working method and the bridge's quirks (void-return errors, timeouts, dialogs, renders that never overwrite, master-fader drift), plus Surge patches by name, MPE breath, arrangement-as-code and verification. Linked into ~/.claude/skills/reaper.

  • lua/helpers/: ReaScripts for what the tools don't cover (load_surge_patch, write_midi, clear_items, stem_check, dump_project). Install with scripts/install_helpers.sh, then run via AddRemoveReaScript + Main_OnCommand (see the skill).

  • tools/make_loop.py: a render becomes a normalised, seamless wav + ogg game loop.

Tools

Tool

Purpose

reaper_ping

Confirm the bridge is alive; returns REAPER version

reaper_get_project_state

Tempo, length, play state, track list

reaper_set_tempo

Set project BPM

reaper_save_project

Save the project

reaper_insert_track / reaper_delete_track

Add / remove tracks

reaper_set_track_name / _mute / _solo / _volume

Track properties (volume in dB)

reaper_create_midi_item

New MIDI item, positioned in beats

reaper_add_midi_notes

Insert notes (beats, pitch, velocity, channel)

reaper_list_track_fx / reaper_add_fx

FX chain management

reaper_get_fx_params / reaper_set_fx_param

Read/write FX parameters

reaper_transport

play / stop / pause / record

reaper_set_edit_cursor

Move edit cursor (seconds)

reaper_render

Bounce the master to a 24-bit WAV (time selection or whole project)

reaper_call

Escape hatch: call any ReaScript function by name

The escape hatch

reaper_call exposes the entire ReaScript API generically: {"func":"CountTracks","args":[0]}. Pointers returned by the API come back as "handle:N" strings (valid within the session) and can be passed back as args to chain calls. Dedicated tools are preferred where they exist, but this means the server is never blocked on a missing wrapper.

Configuration

  • REAPER_MCP_BRIDGE_DIR — override the shared IPC folder (must match on both sides).

  • REAPER_MCP_TIMEOUT — per-call timeout in ms (default 15000; raise for very large MIDI inserts).

Layout

lua/mcp_bridge.lua      # runs inside REAPER: JSON codec, handle registry, dispatch, defer loop
src/bridge.ts           # file-IPC client (serialized calls, atomic writes, stale purge)
src/index.ts            # MCP server entry (stdio)
src/tools/              # tool definitions by domain
src/smoke.ts            # direct bridge round-trip test
scripts/install_bridge.sh

Limitations & notes

  • Handles (handle:N) are per-session; they reset when REAPER restarts.

  • The bridge services requests at REAPER's defer cadence (~30–60/sec), so batch bulk work (insert many notes in one reaper_add_midi_notes call) rather than looping single calls.

  • File-based IPC only; a socket transport could be added later for lower latency.

Credit

Architecture (Lua bridge + external server, file IPC, generic dispatch) is informed by the prior Python projects Aavishkar-Kolte/reaper-daw-mcp-server and shiehn/total-reaper-mcp. This is an independent macOS Node/TypeScript implementation.

Available Tools

20 tools
reaper_add_fxAdd FX to trackA

Add an FX/plugin to a track by name (e.g. 'ReaEQ', 'ReaComp', or a VST name). Returns the new FX index. Matching is fuzzy on the plugin name.

Inputs: fx_name (required), track_index (required).

reaper_add_midi_notesAdd MIDI notesA

Add MIDI notes to the active take of an existing MIDI item. Positions and lengths are in beats relative to the item start. Insert many notes in one call for chords/melodies.

Inputs: notes (required), item_index (required), track_index (required).

reaper_callRaw ReaScript call (advanced)A

Escape hatch: call ANY ReaScript API function by name with positional args, for operations the dedicated tools don't cover. Example: {"func":"CountTracks","args":[0]}. Pointers returned by the API come back as "handle:N" strings, valid only within this REAPER session; pass them back verbatim as args to chain calls. Prefer the dedicated reaper_* tools when one exists.

Inputs: func (required), args.

reaper_create_midi_itemCreate MIDI itemA

Create an empty MIDI item on a track, positioned and sized in beats (quarter notes). Returns the item's index on that track, which you pass to reaper_add_midi_notes.

Inputs: track_index (required), start_beat, length_beat.

reaper_delete_trackDelete trackA

Delete the track at the given 0-based index.

Inputs: index (required).

reaper_get_fx_paramsGet FX parametersA

List all parameters of an FX on a track (index, name, current value, min, max). Values are normalized as the plugin reports them.

Inputs: fx_index (required), track_index (required).

reaper_get_project_stateGet project stateA

Return the current project's tempo (BPM), length in seconds, transport play state, and the list of tracks (index, name, item count, mute/solo, volume in dB). Use this to orient before making changes.

Inputs: no named parameters.

reaper_insert_trackInsert trackA

Insert a new track at the given index (0-based). Omit index to append at the end. Returns the new track's index.

Inputs: name, index.

reaper_list_track_fxList track FXA

List the FX on a track (index, name, enabled state).

Inputs: track_index (required).

reaper_pingPing REAPERA

Check that the REAPER bridge is alive. Returns the REAPER version. Call this first to confirm the connection.

Inputs: no named parameters.

reaper_renderRender to WAVA

Render (bounce) the project master to a 24-bit WAV file on disk. By default renders the current time selection (your loop); set bounds='project' for the whole project. Returns the absolute file path and size. Renders headlessly — no dialog.

Inputs: bounds, output_path.

reaper_save_projectSave projectA

Save the current REAPER project to disk.

Inputs: no named parameters.

reaper_set_edit_cursorMove edit cursorA

Move the edit cursor to a time position in seconds.

Inputs: seconds (required).

reaper_set_fx_paramSet FX parameterA

Set one parameter of an FX by parameter index. Use reaper_get_fx_params to discover indices and ranges.

Inputs: value (required), fx_index (required), param_index (required), track_index (required).

reaper_set_tempoSet project tempoA

Set the project master tempo in BPM.

Inputs: bpm (required).

reaper_set_track_muteMute/unmute trackC

Set the mute state of a track.

Inputs: index (required), muted (required).

reaper_set_track_nameRename trackB

Set the name of the track at the given index.

Inputs: name (required), index (required).

reaper_set_track_soloSolo/unsolo trackC

Set the solo state of a track.

Inputs: index (required), soloed (required).

reaper_set_track_volumeSet track volumeA

Set a track's volume in decibels (0 dB = unity, negative = quieter).

Inputs: db (required), index (required).

reaper_transportTransport controlA

Control playback: play, stop, pause, or record. Returns the resulting play state (0=stopped, 1=playing, 2=paused, 4=recording as bit flags).

Inputs: action (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 20 tools

    Disambiguation4/5

    Most tools are clearly separated by resource and action (tempo, track, MIDI item, FX, transport). The only potential confusion is reaper_get_project_state vs reaper_list_track_fx (both return state info) and reaper_call as an escape hatch could overlap with any dedicated tool, but descriptions mitigate this.

    Naming Consistency5/5

    All tools follow a consistent reaper_verb_noun pattern: reaper_ping, reaper_get_project_state, reaper_set_tempo, reaper_insert_track, reaper_add_midi_notes, etc. The naming is uniform and predictable.

    Tool Count4/5

    20 tools is on the higher end but appropriate for a DAW control surface covering project state, tracks, MIDI, FX, transport, and rendering. Each tool serves a distinct function, though a few could be consolidated (e.g., transport and edit cursor).

    Completeness4/5

    The toolset covers core DAW workflows: project state, track management, MIDI creation/editing, FX parameter control, transport, and rendering. Missing operations like track duplication, item deletion, or FX removal are notable but can be worked around via reaper_call.

    Maintenance

    ActivitySlowing
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers