reaper-mcp-v2
AnqiPinku/reaper-mcp-v2
REAPER MCP v2 server and Lua bridge for controlling REAPER from MCP clients.
Instalação
npx convez-ai AnqiPinku/reaper-mcp-v21 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
README
A tradução para o português deste README ainda está na fila.
REAPER MCP (v2)
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.
| Original | v2 | |
|---|---|---|
| Polling | scans request_1.json … request_1000.json every defer tick | one request.json, one file_exists per tick |
| JSON | hand-rolled, broke on Windows paths | correct recursive-descent parser (\uXXXX, nesting, control chars) |
| Dispatch | 212 hand-written elseif handlers + a generic fallback | curated DSL + generic reaper.* + run_lua; ~500 lines total |
| Pointers | "Cannot use track pointer from previous call" | validated handle registry, pointers round-trip |
| Noise | ShowConsoleMsg on every request | quiet by default (DEBUG=true to trace) |
| Server | external Python package, lost | zero-dependency stdlib, included + tested |
| Time | raw seconds/PPQ | musical 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
- Open REAPER.
Actions→Show action list→New action→Load ReaScript…- Choose
bridge/reaper_mcp_bridge.lua, then Run it. (It registers itself and keeps running viareaper.defer.) You'll seeREAPER MCP Bridge v2 readyin 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 (returna value). Best for multi-step work that would otherwise need many round-trips.
Environment variables
| var | meaning | default |
|---|---|---|
REAPER_MCP_IPC_DIR | IPC mailbox dir (must match on both sides) | %APPDATA%\reaper-mcp-ipc |
REAPER_MCP_TIMEOUT | seconds to wait for the bridge | 10 |
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.