nbdy/reaper-mcp

REAPER MCP Server

A Model Context Protocol (MCP) server that provides programmatic control over REAPER DAW through a clean, tool-based interface. Built with FastMCP and python-reapy, this server enables AI assistants and automation tools to interact with REAPER projects.

Features

• Project Management - Project details, initialization, save, playback state, undo/redo, time conversions
• Playback Control - Start, pause, stop, record, cursor and time selection management
• Markers & Regions - Add, list, and manage markers and regions
• Track Operations - Create, delete, configure tracks (volume, pan, mute, solo, color, selection)
• Tempo Control - Get/set project BPM
• MIDI - Generate and import MIDI notes, patterns, and files
• FX & Plugins - List, add, and control VST plugins and parameters
• Audio Samples - Manage sample directories, search, import, and time-stretch audio files

Prerequisites

• REAPER installed with ReaScript enabled
• python-reapy bridge configured for out-of-process control
• Python 3.11+

Note: The server must be able to communicate with REAPER. Ensure REAPER is running before starting the server.

Installation

Using uv (Recommended)

# Install with uv
uv pip install reaper-mcp

# Or run directly with uv
uv tool install reaper-mcp

Using pip

pip install reaper-mcp

Usage

Run the server (default stdio transport for MCP clients):

python -m reaper_mcp

Run with MCP Proxy (stdio):

uv tool run mcpo --port 8000 -- uv run reaper_mcp

Options:

• --transport {stdio,sse,http,ws,websocket} - Transport protocol (default: stdio)
• --host HOST - Host for network transports (default: 127.0.0.1)
• --port PORT - Port for network transports (default: 8000)
• --path PATH - URL path for HTTP/SSE/WebSocket
• --allow-origin ORIGIN - CORS origin (repeatable)

Example with WebSocket:

python -m reaper_mcp --transport ws --port 9000

MCP Client Configuration

{
  "mcpServers": {
    "reaper": {
      "command": "python",
      "args": ["-m", "reaper_mcp"]
    }
  }
}

{
  "mcpServers": {
    "reaper": {
      "command": "python",
      "args": ["-m", "reaper_mcp"]
    }
  }
}

{
  "mcpServers": {
    "reaper": {
      "command": "python",
      "args": ["-m", "reaper_mcp"]
    }
  }
}

Notes

• Tools are designed to be small and focused - prefer calling multiple tools over complex combined actions
• File paths must be accessible from the REAPER host machine
• Some operations depend on REAPER configuration, OS, and installed plugins
• Tools return helpful error messages when operations are unavailable

Testing

A comprehensive integration test suite is available to validate all 115+ MCP tools across 13 categories. The test suite can optionally use Ollama LLM to generate songs and validate functionality.

Quick Start

cd tests
./run_tests.sh

Features

• Tests all 4 producer workflow methods (create_song_from_scratch, create_variation, continue_song, arrange_song_structure)
• Validates song structure, BPM, tracks, and MIDI content
• Tests all 115+ tools systematically across 13 categories
• Generates comprehensive JSON and text reports
• Optional Ollama LLM integration (granite4:micro-h model)

Configuration

Default Ollama settings (edit tests/test_config.py to customize):

• Host: 10.0.0.192
• Port: 11434
• Model: granite4:micro-h

Run without Ollama:

./run_tests.sh --no-ollama

See for complete documentation including:

• Installation and prerequisites
• Configuration options
• Test phases and categories
• Sample output and success criteria
• Troubleshooting guide
• Architecture details

Links

• REAPER DAW
• FastMCP
• python-reapy
• Model Context Protocol