convez.ai
MCP Server
AnqiPinku

reaper-mcp-v2

AnqiPinku/reaper-mcp-v2

Ver no GitHub
InicialPluginScore · de 0 a 100

REAPER MCP v2 server and Lua bridge for controlling REAPER from MCP clients.

Instalação

$npx convez-ai AnqiPinku/reaper-mcp-v2

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
6
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 3 meses
Versão
v0.1.0
Issues abertas
0
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

REAPER MCP (v2)

CI

Drive REAPER from an MCP client (Claude Code, Claude Desktop, …). Two pieces:

 MCP client  ──stdio JSON-RPC──►  server/reaper_mcp_server.py
                                          │  (single-file IPC)
                                          ▼
                              %APPDATA%\reaper-mcp-ipc\{request,response}.json
                                          ▲
                                          │  reaper.defer poll
                              bridge/reaper_mcp_bridge.lua  (runs inside REAPER)

The IPC "mailbox" lives at a fixed ASCII path (%APPDATA%\reaper-mcp-ipc, e.g. C:\Users\you\AppData\Roaming\reaper-mcp-ipc). Both sides derive it independently from %APPDATA%, so it does not depend on where REAPER is installed — a non-ASCII install/project path can never corrupt the file channel, and the portable vs. installed REAPER can't end up watching different directories.

The server is pure Python stdlib — no pip install needed. The bridge is a single self-contained Lua ReaScript.

Why this is better than the original bridge

The “original bridge” compared below is TwelveTake-Studios/reaper-mcp (MIT). This project is an independent reimplementation of its file-mailbox IPC approach — see Credits.

Originalv2
Pollingscans request_1.json … request_1000.json every defer tickone request.json, one file_exists per tick
JSONhand-rolled, broke on Windows pathscorrect recursive-descent parser (\uXXXX, nesting, control chars)
Dispatch212 hand-written elseif handlers + a generic fallbackcurated DSL + generic reaper.* + run_lua; ~500 lines total
Pointers"Cannot use track pointer from previous call"validated handle registry, pointers round-trip
NoiseShowConsoleMsg on every requestquiet by default (DEBUG=true to trace)
Serverexternal Python package, lostzero-dependency stdlib, included + tested
Timeraw seconds/PPQmusical beats in the high-level tools

🤖 Install with your coding agent

Already have an MCP-capable agent (Claude Code, Codex, …)? Tell it:

Install the REAPER MCP server from https://github.com/AnqiPinku/reaper-mcp-v2 — read AGENTS.md and follow it.

The agent will clone the repo, register the reaper MCP server, and walk you through the one manual step (running the Lua bridge inside REAPER). See AGENTS.md for the exact procedure, or follow the manual steps below.

Setup

1. Start the bridge in REAPER

  1. Open REAPER.
  2. Actions → Show action list → New action → Load ReaScript…
  3. Choose bridge/reaper_mcp_bridge.lua, then Run it. (It registers itself and keeps running via reaper.defer.) You'll see REAPER MCP Bridge v2 ready in the ReaScript console once.

Re-run the action any time to restart the bridge.

2. Register the server with your MCP client

Claude Code — add to .mcp.json (project) or your user config:

{
  "mcpServers": {
    "reaper": {
      "command": "python",
      "args": ["C:\\path\\to\\reaper-mcp-v2\\server\\reaper_mcp_server.py"]
    }
  }
}

Or via CLI:

claude mcp add reaper -- python "C:\path\to\reaper-mcp-v2\server\reaper_mcp_server.py"

3. Try it

Ask the client: "Use reaper_status to check REAPER, then make a 4-bar MIDI drum loop at 124 BPM."

Tools

High-level (think in beats; index = 0-based): reaper_status, list_tracks, add_track, delete_track, update_track, set_tempo, set_time_signature, transport, create_midi_item, add_midi_notes, get_midi_notes, add_track_fx, list_track_fx, get_fx_params, set_fx_param, set_time_selection, add_marker, render_project.

Escape hatches:

  • reaper_call — call any one of REAPER's 600+ ReaScript functions by name.
  • run_lua — execute an arbitrary Lua snippet inside REAPER (return a value). Best for multi-step work that would otherwise need many round-trips.

Environment variables

varmeaningdefault
REAPER_MCP_IPC_DIRIPC mailbox dir (must match on both sides)%APPDATA%\reaper-mcp-ipc
REAPER_MCP_TIMEOUTseconds to wait for the bridge10

Folder Names And Non-ASCII Paths

The IPC channel is ASCII-pinned and independent of the project path, so the folder name is cosmetic. The MCP can work with non-ASCII REAPER/project paths, but an ASCII path for the Python server command is still the safest option on Windows.

Recommended Windows layout:

C:\MCP\reaper-mcp-v2\
  bridge\reaper_mcp_bridge.lua
  server\reaper_mcp_server.py

If you keep the project somewhere else, update only the server path in your MCP client config. The IPC directory does not need to move.

Testing

server/test_server.py runs the whole server against a fake bridge (no REAPER needed) and checks the JSON-RPC handshake, tool list, arg marshalling, generic call and run_lua:

python server/test_server.py

Protocol (for reference)

Request (request.json):

{ "id": "ab12cd34", "func": "add_track", "args": ["Bass", 2] }
{ "id": "ab12cd34", "func": "run_lua", "code": "return reaper.CountTracks(0)" }

Response (response.json):

{ "id": "ab12cd34", "ok": true, "ret": { "index": 2, "name": "Bass" } }
{ "id": "ab12cd34", "ok": false, "error": "no track at index 9" }

Pointers are serialised as { "__handle": "h7" } and can be passed back in.

Credits

This project builds on the file-mailbox IPC bridge design pioneered by TwelveTake-Studios/reaper-mcp (MIT License, Copyright (c) 2024 TwelveTake Studios LLC). The server and bridge here are an independent rewrite, but the core idea — a fixed-path JSON request/response mailbox polled by a stock-Lua ReaScript — originates there. Thanks to TwelveTake Studios for the original work.

Disclaimer

REAPER is a trademark of Cockos Incorporated. This is an independent, unofficial project and is not affiliated with, endorsed by, or sponsored by Cockos Incorporated or TwelveTake Studios.

Ver o original no GitHub

Relacionados