reascript-mcp

MCP server exposing Reaper/ReaScript project-control helpers to AI agents.

This is the first working slice of the Reaper layer for the Asian Sentry agentic music tooling stack. It complements music21-mcp: music21 handles symbolic music reasoning; ReaScript handles project-level DAW control and state readback.

Current tools

Tool	What it does
parse_rpp_project	Parse a .rpp Reaper project file into compact JSON: tempo, time signature, track names, item counts, and media source types. Works without Reaper installed.
generate_reascript	Generate Lua ReaScripts for supported actions. Initial actions: list_tracks and create_midi_item.
write_reascript_file	Generate a supported Lua ReaScript and write it to disk for loading/running in REAPER.

Install

cd reascript-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'

Run tests

python -m pytest -q

Current status: 12 tests passing.

Use as MCP server

python -m reascript_mcp.server

Example MCP config:

{
  "mcpServers": {
    "reascript-mcp": {
      "command": "/path/to/reascript-mcp/.venv/bin/python",
      "args": ["-m", "reascript_mcp.server"],
      "cwd": "/path/to/reascript-mcp"
    }
  }
}

Direct Python examples

from reascript_mcp.tools.parse_rpp_project import parse_rpp_project
from reascript_mcp.tools.generate_reascript import generate_reascript

print(parse_rpp_project("song.rpp"))

script = generate_reascript("list_tracks", {"output_path": "tracks.json"})
print(script["script"])

from reascript_mcp.tools.write_reascript_file import write_reascript_file
write_reascript_file("list_tracks", {"output_path": "tracks.json"})

Next build slices

1. Add a Reaper CLI smoke harness that runs against a disposable config/project and exits cleanly.
2. Add more project-control scripts: create tracks, rename tracks, import MIDI, set tempo map, add markers/regions.
3. Add structured state readback scripts for items, takes, MIDI notes, markers, routing, and FX chains.
4. Connect this to the common musical data model so music21/mido/ReaScript reference the same musical locations.