reaper-mcp
by shvaykovski
README.md
# reaper-mcp
[](https://github.com/shvaykovski/reaper-daw-mcp-server/actions/workflows/ci.yml)
[](LICENSE)


**Control the [REAPER](https://www.reaper.fm) DAW from AI assistants.** reaper-mcp is a [Model Context Protocol](https://modelcontextprotocol.io) server that lets Claude, GPT and other MCP-capable models build sessions, edit tracks, FX, items and MIDI, render, and run broadcast-grade loudness and voice leveling inside your project.
> "Create tracks Kick, Snare, Bass and Pads, color the drums red, put ReaComp on Bass at 4:1, and write an 8-bar Am–F–C–G pad progression from bar 1."
It works with Claude Desktop, Claude Code, OpenAI Codex CLI, ChatGPT (developer mode), the OpenAI Agents SDK, Cursor and any other MCP client.
## Contents
- [Features](#features)
- [How it works](#how-it-works)
- [Requirements](#requirements)
- [Installation](#installation)
- [Connect your AI client](#connect-your-ai-client)
- [Example prompts](#example-prompts)
- [Skills](#skills)
- [Safety](#safety)
- [Configuration](#configuration)
- [Troubleshooting](#troubleshooting)
- [Development](#development)
- [License](#license)
## Features
| Area | What the model can do |
|---|---|
| Project & transport | Inspect the project, play/stop/record, cursor, tempo, loop, save, undo/redo, render |
| Tracks | List, create, delete, rename, volume, pan, mute/solo/arm, color, sends |
| FX | Add/remove plugins, bypass, presets, read and set parameters with human-readable values |
| Items & MIDI | List, move, resize, mute, import media, create MIDI items, add/read/clear notes |
| Markers & regions | List, add, delete |
| Loudness (EBU R128) | LUFS-I, LRA, true peak; per-segment leveling for DJ mixes and podcasts, normalization, peak limiting |
| Voice | Phrase/word leveling, silence trimming, pause and breath ducking |
| Escape hatches | Run any Action List command or arbitrary ReaScript Lua |
43 tools in total; see the full **[tool reference](docs/TOOLS.md)**. Every edit is a single named undo step (`MCP: track.update`, …), so Ctrl/Cmd+Z works as usual.
## How it works
```
AI client ──MCP (stdio or HTTP)──> reaper-mcp (Python) ──files──> reaper_mcp_bridge.lua (inside REAPER) ──> ReaScript API
```
The bridge is a ReaScript running in REAPER's defer loop (~30 Hz). It exchanges one request/response at a time through `<REAPER resource path>/mcp_bridge/` and touches a heartbeat file every second. No extensions (SWS, sockets) are required.
## Requirements
- [REAPER](https://www.reaper.fm) 6 or newer (7 recommended), on macOS, Windows or Linux
- [uv](https://docs.astral.sh/uv/getting-started/installation/) (installs Python 3.10+ and the dependencies for you)
## Installation
### 1. Get the code
```sh
git clone https://github.com/shvaykovski/reaper-daw-mcp-server.git ~/Tools/reaper-mcp
cd ~/Tools/reaper-mcp
uv sync --extra audio
```
Keep the folder somewhere permanent: AI clients run the server from it. The `audio` extra (numpy, scipy, soundfile) powers the loudness tools; without it everything else still works.
### 2. Start the bridge in REAPER
1. In REAPER, open **Options > Show REAPER resource path in explorer/finder** and copy `reaper_mcp_bridge.lua` into its `Scripts` folder.
2. **Actions > Show action list > New action > Load ReaScript…**, pick the file, then **Run**.
3. The console shows `REAPER MCP bridge running: …`. Run the action again to stop it.
To start it with REAPER, create or append to `Scripts/__startup.lua`:
```lua
dofile(reaper.GetResourcePath() .. "/Scripts/reaper_mcp_bridge.lua")
```
REAPER runs the copy in `Scripts`, not the one in the repository. After updating, copy it again and restart the bridge.
## Connect your AI client
In the examples below, replace `/path/to/reaper-mcp` with the absolute path of the cloned folder. GUI apps don't inherit your shell `PATH`, so use the absolute path to `uv` (`which uv` on macOS/Linux, `where uv` on Windows) when `uv` alone is not found.
### Claude Desktop
Edit `claude_desktop_config.json` (**Settings > Developer > Edit Config**):
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"reaper": {
"command": "/opt/homebrew/bin/uv",
"args": ["run", "--extra", "audio", "--directory", "/path/to/reaper-mcp", "reaper-mcp"]
}
}
}
```
Restart Claude Desktop.
### Claude Code
```sh
claude mcp add reaper -- uv run --extra audio --directory /path/to/reaper-mcp reaper-mcp
```
### OpenAI Codex CLI
```sh
codex mcp add reaper -- uv run --extra audio --directory /path/to/reaper-mcp reaper-mcp
```
Or add it to `~/.codex/config.toml`:
```toml
[mcp_servers.reaper]
command = "uv"
args = ["run", "--extra", "audio", "--directory", "/path/to/reaper-mcp", "reaper-mcp"]
startup_timeout_sec = 60 # the first start installs dependencies
tool_timeout_sec = 1800 # renders and loudness passes on long mixes take a while
```
### ChatGPT (developer mode)
ChatGPT connects to MCP servers over HTTPS only, so run the server in HTTP mode and expose it through a tunnel:
```sh
# 1. Server on http://127.0.0.1:8000/mcp
uv run --extra audio --directory /path/to/reaper-mcp reaper-mcp \
--transport streamable-http --port 8000 --no-code-execution \
--allowed-host <your-tunnel-domain>
# 2. Public HTTPS URL for it, e.g. with cloudflared or ngrok
cloudflared tunnel --url http://localhost:8000
```
In ChatGPT, turn on **Settings > Apps & Connectors > Advanced settings > Developer mode**, create a connector with the URL `https://<your-tunnel-domain>/mcp`, and enable it in a chat. Read [Safety](#safety) first: anyone who has the tunnel URL can control your REAPER session.
### OpenAI Agents SDK
```python
from agents import Agent, Runner
from agents.mcp import MCPServerStdio
async with MCPServerStdio(
params={"command": "uv", "args": ["run", "--extra", "audio", "--directory", "/path/to/reaper-mcp", "reaper-mcp"]},
client_session_timeout_seconds=120,
) as reaper:
agent = Agent(name="Engineer", instructions="You operate REAPER.", mcp_servers=[reaper])
result = await Runner.run(agent, "Add a Reverb bus and send all vocal tracks to it at -12 dB")
```
### Other clients (Cursor, VS Code, Windsurf, …)
Any client that launches stdio MCP servers takes the same command:
```json
{
"mcpServers": {
"reaper": {
"command": "uv",
"args": ["run", "--extra", "audio", "--directory", "/path/to/reaper-mcp", "reaper-mcp"]
}
}
}
```
Clients that only speak HTTP can use `--transport streamable-http` and `http://127.0.0.1:8000/mcp`.
## Example prompts
**Session building**
- "Set up a session for a pop song at 104 BPM: drums, bass, keys, two guitars, lead and backing vocals, colored by family, with a reverb bus."
- "Add regions Intro (1–9), Verse (9–25), Chorus (25–41)."
- "Write an 8-bar Am–F–C–G pad progression on Pads starting at bar 1."
**Mixing**
- "Pull Bass down 3 dB and send Pads to a new Reverb bus at -12 dB."
- "Put ReaEQ on the vocal and cut 3 dB at 300 Hz."
- "Which tracks have FX bypassed?"
**Loudness and mastering**
- "Analyze the loudness of the mix track and tell me which sections are louder than the rest."
- "This DJ mix has a marker at each track start: even out the tracks without touching the dynamics inside them."
- "Normalize the master stem to -14 LUFS with a -1 dBTP ceiling, dry run first."
**Podcast and voice**
- "On the Host track, shorten long silences, level the voice, then duck the breaths."
## Skills
[`examples/skills/reaper-session-setup`](examples/skills/reaper-session-setup/SKILL.md) is a small [Agent Skill](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview) that turns a short brief into a full session (tempo, color-coded tracks, reverb bus, stock FX, song regions, an optional MIDI idea). It shows how to package a repeatable workflow on top of the tools.
- **Claude Code**: copy the folder into `~/.claude/skills/` (all projects) or `.claude/skills/` (one project).
- **Claude apps**: zip the folder and upload it under **Settings > Capabilities > Skills**.
- **Other agents** that support the `SKILL.md` format load the same folder from their skills directory. For agents without skills support, paste the file's body into the system prompt.
## Safety
- **Undo**: every edit is one undo step. Ask the model to `reaper_undo`, or press Ctrl/Cmd+Z.
- **Code execution**: `reaper_execute_lua` and `reaper_run_action` run arbitrary code with REAPER's permissions, including file system access. Clients that ask for approval before destructive tools will prompt for them. Start the server with `--no-code-execution` to remove them.
- **HTTP mode**: the server listens on `127.0.0.1` only and rejects unknown `Host` headers (DNS-rebinding protection). It has no authentication, so a tunnel makes your REAPER session reachable by anyone with the URL. Use `--no-code-execution`, keep the tunnel URL private and stop it when you are done.
- **Files**: `reaper_insert_media` and `reaper_render` read and write the paths the model gives them.
## Configuration
| Option | Default | Description |
|---|---|---|
| `--transport` | `stdio` | `stdio` for local clients, `streamable-http` to serve `http://127.0.0.1:PORT/mcp` |
| `--port` | `8000` | HTTP port |
| `--allowed-host HOST` | – | Extra `Host` header to accept over HTTP (e.g. a tunnel domain); repeatable |
| `--no-code-execution` | off | Remove `reaper_execute_lua` and `reaper_run_action` |
| `REAPER_MCP_DIR` env var | `<resource path>/mcp_bridge` | Bridge folder, for portable installs or a custom resource path |
Default resource paths: macOS `~/Library/Application Support/REAPER`, Windows `%APPDATA%\REAPER`, Linux `~/.config/REAPER`.
## Troubleshooting
- **"REAPER bridge is not responding"**: the bridge script is not running, REAPER is closed, or a modal dialog is open (the defer loop pauses while modal windows are up). With a portable install, set `REAPER_MCP_DIR`.
- **Loudness tools need the audio extra**: run `uv sync --extra audio` and add `--extra audio` to the server command.
- **"cannot read … supported: WAV, FLAC, AIFF, OGG, MP3"**: glue or render items in other formats (e.g. m4a) first. The voice tools read any format.
- **FX not found**: use the name from the FX browser; for ambiguous plugins include the prefix, e.g. `VST3: Pro-Q 3 (FabFilter)`.
- **A tool times out on long projects**: raise the client's tool timeout (`tool_timeout_sec` in Codex). Renders and actions that open dialogs block REAPER until finished; other calls wait.
- **ChatGPT cannot connect**: check that the URL ends in `/mcp`, the tunnel domain is passed with `--allowed-host`, and the server log shows the request.
## Development
```sh
uv sync --extra audio --group dev
uv run pytest -q # no REAPER needed
uvx ruff check .
```
See [CONTRIBUTING.md](CONTRIBUTING.md) and [AGENTS.md](AGENTS.md) for the code layout and how to add a tool.
## License
[MIT](LICENSE) © Max Shvaykovski · [LinkedIn](https://www.linkedin.com/in/maximshvaykovski/)
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues