# REAPER MCP Server

[![PyPI version](https://img.shields.io/pypi/v/reaper-mcp.svg)](https://pypi.org/project/reaper-mcp/)
[![Python Version](https://img.shields.io/pypi/pyversions/reaper-mcp.svg)](https://pypi.org/project/reaper-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Tests](https://github.com/nbdy/reaper-mcp/actions/workflows/test.yml/badge.svg)](https://github.com/nbdy/reaper-mcp/actions/workflows/test.yml)
[![codecov](https://codecov.io/gh/nbdy/reaper-mcp/branch/main/graph/badge.svg)](https://codecov.io/gh/nbdy/reaper-mcp)

A Model Context Protocol (MCP) server that provides programmatic control over [REAPER DAW](https://www.reaper.fm/) through a clean, tool-based interface. Built with [FastMCP](https://github.com/jlowin/fastmcp) and [python-reapy](https://github.com/RomeoDespres/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)

```bash
# Install with uv
uv pip install reaper-mcp

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

### Using pip

```bash
pip install reaper-mcp
```

## Usage

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

```bash
python -m reaper_mcp
```

**Run with MCP Proxy (stdio):**
```bash
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:**
```bash
python -m reaper_mcp --transport ws --port 9000
```

## MCP Client Configuration

<details>
<summary><b>Claude Desktop</b></summary>

Add to `claude_desktop_config.json`:

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

</details>

<details>
<summary><b>Cline (VS Code)</b></summary>

Add to MCP settings:

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

</details>

<details>
<summary><b>Continue (VS Code)</b></summary>

Add to `config.json`:

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

</details>

<details>
<summary><b>Using uv</b></summary>

For any client, replace `"command": "python"` with `"command": "uv"` and `"args": ["run", "python", "-m", "reaper_mcp"]`

</details>

## 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

```bash
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:
```bash
./run_tests.sh --no-ollama
```

See [tests/README.md](tests/README.md) 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](https://www.reaper.fm/)
- [FastMCP](https://github.com/jlowin/fastmcp)
- [python-reapy](https://github.com/RomeoDespres/reapy)
- [Model Context Protocol](https://modelcontextprotocol.io/)
