Skip to main content
Glama
README.md
# reaper-mcp

[![CI](https://github.com/shvaykovski/reaper-daw-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/shvaykovski/reaper-daw-mcp-server/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)
![MCP](https://img.shields.io/badge/MCP-server-black)

**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/)