Content
# MCP Reaper (mcpreaper)
**Version 2.0**
A Reaper audio editor control interface based on Model Context Protocol (MCP), allowing large language models (LLM) to fully operate Reaper through tool calls.
## Table of Contents
- [Home Resources (Test Project)](#home-resources-test-project)
- [Features](#features)
- [Installation Requirements](#installation-requirements)
- [Installation Steps](#installation-steps)
- [Usage](#usage)
- [Tool Classification and Detailed Description](#tool-classification-and-detailed-description)
- [Error Handling Mechanism](#error-handling-mechanism)
- [Example Usage](#example-usage)
- [Project Structure](#project-structure)
- [Test Scripts](#test-scripts)
- [LLM Client Configuration Tutorial](#llm-client-configuration-tutorial)
- [Troubleshooting](#troubleshooting)
- [Project Description](#project-description)
- [Contact Information](#contact-information)
- [License](#license)
## Home Resources (Test Project)
The current repository has built-in test project resources (about 3 minutes of Qing dynasty background music):
- Project file: `ReaperProject/testreaper.rpp`
- Audio file: `ReaperProject/testreaper.wav`
- Image file: `ReaperProject/testmcp.png`
<audio controls src="ReaperProject/testreaper.wav"></audio>
If the browser does not support the player, you can directly download the audio: [testreaper.wav](ReaperProject/testreaper.wav)
## Features
### Core Features
- **Track Management**: Create, delete, rename, select tracks, set volume, pan, mute, solo, recording preparation status
- **Media Item**: Import audio, move, resize, split, delete item, set item volume and pan
- **Playback Control**: Play, stop, pause, record, loop playback, set playback position
- **FX Plugin**: Add, remove, enable/disable FX plugins, set plugin parameters
### Advanced Features
- **Marker Management**: Create, delete, rename markers and regions
- **MIDI Editing**: Create MIDI items, insert, modify, delete MIDI notes, handle CC events and text events
- **Project Management**: Save project, set BPM/tempo, undo/redo, audio normalization
- **Automation Envelope**: Add, delete, get envelope control points, set curve shape
- **Track Send**: Create, delete, set send volume and pan, view send and receive information
- **Rendering Export**: Render project, set rendering parameters, render selected tracks, batch render tracks
- **Audio Processing**: Record, normalize, fade in/out, pitch adjustment, stretch, remove silence
- **EQ/DSP Processing**: ReaEQ parameter control, compressor settings, FIR filter, EQ presets
- **Film and TV Sound Production**: Video import, timecode synchronization, ADR/foley/sound effect track group creation, batch rendering
- **Waveform Generation**: Sine wave, square wave, triangle wave, sawtooth wave, white/pink/brown noise, chord generation
## Installation Requirements
| Dependency | Version Requirement | Description |
| --- | --- | --- |
| Python | **3.11** | REAPER 7.73 does not support Python 3.14, must use Python 3.11 |
| REAPER | 6.0+ | Audio editor, must be installed |
| reapy | latest | Python library for controlling Reaper |
| mcp | latest | Model Context Protocol SDK |
## Installation Steps
### 1. Clone the Repository
```bash
git clone https://github.com/PangXingQing/mcpreaper.git
cd mcpreaper
```
### 2. Create a Virtual Environment
```bash
python -m venv .venv
```
### 3. Activate the Virtual Environment
**Windows:**
```bash
.venv\Scripts\activate
```
**macOS/Linux:**
```bash
source .venv/bin/activate
```
### 4. Install Dependencies
```bash
pip install mcp[cli] python-reapy numpy scipy matplotlib
```
### 5. Configure Reaper
> ⚠️ **Important**: This section has been verified with Windows + REAPER v7.73 + Python 3.11 actual environment.
This project uses the **reapy** library to control Reaper through the ReaScript Distant API. Here are the complete configuration steps:
#### 5.1 Python Version Preparation
REAPER 7.73's ReaScript does not support Python 3.14. **Must use Python 3.11**.
```bash
# Check the installed Python version
py -0p
# If Python 3.11 is not installed, install it through winget
winget install -e --id Python.Python.3.11
# Confirm the installation path and DLL
py -3.11 -c "import sys,os; print('exe=', sys.executable); print('dll311=', os.path.exists(os.path.join(sys.base_prefix, 'python311.dll')))"
```
Expected output:
```
exe= D:\Program Files\Python311\python.exe
dll311= True
```
#### 5.2 Create and Configure the Virtual Environment
```bash
# Remove the old virtual environment (if it exists)
if (Test-Path '.venv') { Remove-Item -Recurse -Force '.venv' }
# Create a virtual environment with Python 3.11
py -3.11 -m venv .venv
# Install dependencies
.venv\Scripts\python.exe -m pip install --upgrade pip
.venv\Scripts\python.exe -m pip install mcp[cli] python-reapy numpy scipy matplotlib
```
#### 5.3 Enable Python ReaScript
1. Open Reaper
2. Go to `Options` → `Preferences` → `Plug-ins` → `ReaScript`
3. Check **Enable Python for use with ReaScript**
4. Set **Custom path to Python dll directory** to:
```
D:\Program Files\Python311
```
(directory containing `python311.dll`)
5. Click **OK** and restart Reaper
#### 5.4 Enable Distant API + Web Interface (Critical Steps)
This is the most important step! reapy communicates with Reaper through **Distant API**, which needs to be enabled within Reaper.
**Recommended method: Run the enable script in Reaper**
1. Ensure Reaper is running
2. Open Reaper's **Actions** dialog (`Shift + ?` or `Actions` → `Show action list...`)
3. Click `ReaScript: Load script...`
4. Select the script in the project:
```
scripts\enable_reapy_server.lua
```
5. If Lua reports an error `attempt to call a nil value (field 'set_config_var_string')` or pops up "Partial Success",
manually add Web Interface: `Options → Preferences → Control/OSC/web → Add → Web Browser Interface`, set the port to `2307`
6. The script will automatically create `enable_distant_api.txt` and fix the Web Interface port to `2307`
**Verify Web Interface**
Access the following URL in a browser, and you should see the "REAPER control" page:
```
http://<your IPv4 address>:2307/
```
#### 5.5 Configure reapy Connection Parameters
The project now only retains a single path:
- Execute `scripts/enable_reapy_server.lua` in Reaper
- Web Interface listens on `2307`
- MCP uses the local IPv4 + port `2307` to connect
The connection configuration is uniformly managed by `utils/reaper_client.py` in the project and no longer relies on the old `localhost/127.0.0.1/multi-port` fallback.
#### 5.6 Start the Binding Script (Optional)
It is recommended to directly use the task in the project:
```bash
mcpreaper: activate reapy server instructions
```
Then load and run `scripts/enable_reapy_server.lua` in the Reaper Action List.
### 6. Verify Installation
#### 6.1 Check Python and Virtual Environment
```bash
.venv\Scripts\python.exe -V
# Python 3.11.9
```
#### 6.2 Verify Reaper Connection
Ensure Reaper is running, then run:
```bash
.venv\Scripts\python.exe -c "import reapy; reapy.connect(); print('Successfully connected to Reaper!')"
```
If the connection fails, it may be due to:
1. Reaper is not running
2. Distant API is not enabled
3. Python DLL path configuration error
4. Local IPv4 not recognized (can set environment variable `REAPER_WEB_HOST`)
#### 6.3 Test MCP Service
```bash
.venv\Scripts\python.exe main.py
```
The service will start and wait for the LLM client to connect through stdio.
#### 6.4 Port Connectivity Check
```powershell
# Use the script in the project to check (automatically select the effective IPv4)
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\check_web_2307.ps1
```
## Usage
### Start MCP Server
```bash
python main.py
```
The server will start with stdio protocol and wait for the LLM client to connect.
### Using in LLM
The MCP server provides the following tools for LLM to call. All tools return responses in a unified format:
**Successful Response:**
```json
{
"success": true,
"message": "Operation successful description",
"data": { ... }
}
```
**Error Response:**
```json
{
"success": false,
"error_type": "Error type",
"error": "Error message",
"detail": "Detailed information",
"suggestion": "Solution suggestion"
}
```
## Tool Classification and Detailed Description
### Track Operations
| Tool Name | Parameters | Description |
| --- | --- | --- |
| `reaper_add_track` | `track_name: str` | Create a track |
| `reaper_delete_track` | `track_name: str` | Delete a track |
| `reaper_rename_track` | `track_name: str, new_name: str` | Rename a track |
| `reaper_select_track` | `track_name: str` | Select a track |
| `reaper_get_all_tracks` | None | Get all track information |
| `reaper_get_all_track_names` | None | Get all track names |
| `reaper_get_track_info` | `track_name: str` | Get the information of a specified track |
| `reaper_set_track_volume` | `track_name: str, volume: float` | Set track volume (linear value 0-1) |
| `reaper_set_track_volume_db` | `track_name: str, volume_db: float` | Set track volume (decibel value) |
| `reaper_set_track_pan` | `track_name: str, pan: float` | Set track pan (-1 to 1) |
| `reaper_set_track_mute` | `track_name: str, mute: bool` | Set track mute |
| `reaper_set_track_solo` | `track_name: str, solo: bool` | Set track solo |
| `reaper_set_track_rec_arm` | `track_name: str, rec_arm: bool` | Set recording preparation |
### Media Item Operations
| Tool Name | Parameters | Description |
| --- | --- | --- |
| `reaper_insert_audio_to_track` | `track_name: str, file_path: str, position: float` | Import audio to track |
| `reaper_get_track_items` | `track_name: str` | Get all item information of a track |
| `reaper_move_item` | `track_name: str, item_index: int, new_position: float` | Move an item |
| `reaper_resize_item` | `track_name: str, item_index: int, new_length: float` | Resize an item |
| `reaper_delete_item` | `track_name: str, item_index: int` | Delete an item |
| `reaper_split_item` | `track_name: str, item_index: int, split_position: float` | Split an item |
| `reaper_set_item_volume` | `track_name: str, item_index: int, volume: float` | Set item volume |
| `reaper_set_item_pan` | `track_name: str, item_index: int, pan: float` | Set item pan |
### Playback Control
| Tool Name | Parameters | Description |
| --- | --- | --- |
| `reaper_play` | None | Start playing |
| `reaper_stop` | None | Stop playing |
| `reaper_pause` | None | Pause playing |
| `reaper_toggle_play` | None | Toggle play/pause |
| `reaper_record` | None | Start recording |
| `reaper_go_to_start` | None | Move to project start |
| `reaper_go_to_end` | None | Move to project end |
| `reaper_set_play_position` | `time: float` | Set playback position (seconds) |
| `reaper_get_play_position` | None | Get playback position and status |
| `reaper_set_loop_range` | `start_time: float, end_time: float` | Set loop range |
| `reaper_toggle_loop` | None | Toggle loop mode |
### FX Plugin Operations
| Tool Name | Parameters | Description |
| --- | --- | --- |
| `reaper_add_fx_to_track` | `track_name: str, fx_name: str` | Add an FX plugin |
| `reaper_remove_fx_from_track` | `track_name: str, fx_index: int` | Remove an FX plugin |
| `reaper_get_track_fx_list` | `track_name: str` | Get FX plugin list |
| `reaper_toggle_fx` | `track_name: str, fx_index: int` | Toggle FX enable status |
| `reaper_set_fx_param` | `track_name: str, fx_index: int, param_index: int, value: float` | Set FX parameter |
| `reaper_get_fx_params` | `track_name: str, fx_index: int` | Get FX parameter information |
| `reaper_bypass_all_fx` | `track_name: str, bypass: bool` | Bypass all FX |
### Marker Operations
| Tool Name | Parameters | Description |
| --- | --- | --- |
| `reaper_add_marker` | `name: str, position: float` | Add a marker |
| `reaper_delete_marker` | `name: str` | Delete a marker |
| `reaper_rename_marker` | `old_name: str, new_name: str` | Rename a marker |
| `reaper_get_all_markers` | None | Get all markers |
| `reaper_go_to_marker` | `name: str` | Jump to marker position |
### MIDI Operations
| Tool Name | Parameters | Description |
| --- | --- | --- |
| `reaper_insert_midi_item` | `track_name: str, position: float, length: float` | Insert a MIDI item |
| `reaper_add_midi_note` | `track_name: str, item_index: int, pitch: int, start_time: float, end_time: float, velocity: int` | Add a MIDI note |
| `reaper_set_midi_note_velocity` | `track_name: str, item_index: int, note_index: int, velocity: int` | Set MIDI note velocity |
| `reaper_delete_midi_note` | `track_name: str, item_index: int, note_index: int` | Delete a MIDI note |
| `reaper_get_midi_notes` | `track_name: str, item_index: int` | Get MIDI note list |
Project Operations
| Tool Name | Parameters | Description |
|---------|------|------|
| `reaper_save_project` | None | Save Project |
| `reaper_save_project_as` | `file_path: str` | Save Project As |
| `reaper_set_project_bpm` | `bpm: float` | Set Project BPM |
| `reaper_get_project_bpm` | None | Get Project BPM |
| `reaper_undo` | None | Undo Operation |
| `reaper_redo` | None | Redo Operation |
| `reaper_calculate_normalization` | `track_name: str` | Calculate Audio Normalization |
| `reaper_normalize_audio` | `track_name: str, target_db: float` | Normalize Audio |
### Envelope Operations
| Tool Name | Parameters | Description |
|---------|------|------|
| `reaper_get_track_envelopes` | `track_name: str` | Get All Envelopes of a Track |
| `reaper_add_envelope_point` | `track_name: str, envelope_index: int, time: float, value: float, shape: int` | Add Point to Envelope |
| `revelope_point` |_name: str, envelope point_index: int` | Delete Envelope Point |
| `reaper_get_envelope_points` | `track_name: str, envelope_index: int` | Get All Points of an Envelope |
| `reaper_get_envelope_value_at_time` | `track_name: str, envelope_index: int, time: float` | Get Envelope Value at Specific Time |
| `reaper_clear_envelope_points` | `track_name: str, envelope_index: int` | Clear All Points of an Envelope |
### Track Send Operations
| Tool Name | Parameters | Description |
|---------|------|------|
| `reaper_create_track_send` | `source_track_name: str, destination_track_name: str` | Create Send Between Tracks |
| `reaper_delete_track_send` | `track_name: str, send_index: int` | Delete Track Send |
| `reaper_get_track_sends` | `track_name: str` | Get All Sends of a Track |
| `reaper_set_send_volume` | `track_name: str, send_index: int, volume: float` | Set Send Volume |
| `reaper_set_send_pan` | `track_name: str, send_index: int, pan: float` | Set Send Pan |
| `reaper_get_track_receives` | `track_name: str` | Get All Receives of a Track |
### Render and Export Operations
| Tool Name | Parameters | Description |
|---------|------|------|
| `reaper_render_project` | `output_path: str, render_mode: int` | Render Project |
| `reaper_render_selected_tracks` | `output_path: str, track_names: list` | Render Selected Tracks |
| `reaper_get_render_settings` | None | Get Current Render Settings |
| `reaper_set_render_settings` | `sample_rate: int, bit_depth: int` | Set Render Settings |
| `reaper_render_item_as_new_take` | `track_name: str, item_index: int` | Render Item as New Take |
| `reaper_create_render_marker_region` | `start_time: float, end_time: float, name: str` | Create Render Marker Region |
### MIDI Extension Operations
| Tool Name | Parameters | Description |
|---------|------|------|
| `reaper_insert_midi_cc` | `track_name: str, item_index: int, cc_number: int, position_ppq: int, value: int, channel: int` | Insert CC Event |
| `reaper_get_midi_cc_events` | `track_name: str, item_index: int` | Get All CC Events |
| `reaper_insert_midi_text_event` | `track_name: str, item_index: int, position_ppq: int, text: str, event_type: str` | Insert Text Event |
| `reaper_get_midi_text_events` | `track_name: str, item_index: int` | Get All Text Events |
| `reaper_quantize_midi_notes` | `track_name: str, item_index:_div: int, strength: float` | Quantize MIDI Notes |
| `reaper_transpose_midi_notes` | `track_name: str, item_index: int, semitones: int` | Transpose MIDI Notes |
| `reaper_get_midi_item_info` | `track_name: str, item_index: int` | Get MIDI Item Info |
### Audio Processing Operations
| Tool Name | Parameters | Description |
||
| `reaper_record_on_track` | ` str` | on Track |
| `_recording` | Stop Recording |
|_normalize_audio_item `track_name: item_index: int,: float` || `reade_audio_item` | `track_name: str, int, fade_in float, fade_out float` | Set Fade |
| `reaper_stretch_audio_item` | `track_name: str, item_index: int, new_length: float` | Stretch Audio Item |
| `reaper_change_audio_pitch` | `track_name: str, item_index: int, semitones: int` | Change Audio Pitch |
| `reaper_get_audio_item_info` |: str,: int` | Item Info |
|_remove_audio_silence` | ` str, item int, threshold_db: Remove Silence |
reaper_insert_audio_cross `track_name, item_index1:_index2: int` | Insert Crossfade |
reaper_apply_audio_processing` | `track_name:_index: int: str` | |
### EQ/DSP Processing Operations
| Tool Parameters | Description |
------|
| `_add_reaeqtrack str` | Add ReaEQ Pluginreaper_seteq_band` |: str, band, freq_h float, gain_db: q_factor: float_type: str` |aEQ Band Parameters `reaper_get_reaeq_band` | `track_name: str, band_index: int` | Get ReaEQ Band Parameters |
|aper_reset_reaeq `track_name: | Reset ReaEQ `reaper_apply` | `track_name, preset_name: str Apply EQ Preset |
| `reaper_addomp` | `: str` | Add Compressor |
|aper_set_reacomp | `track_name: str, threshold_db: ratio: float, attack float, release_ms, knee_db: float` | Set ReaComp `reaperir` | `: str` |aFIR Equalizer |
### Film and Sound Production Operations Name | Parameters | Description |
|---------|------|------|
| `reaper_import_video` | `file_path: str` | Import Video File |
| `recode_format` |: str` Timecode Format |
reaper_set_frame_rateframe_rate: | Set Project Frame Rate `reaper_setcode` | ` int, minutes: int, seconds: int, frames: int` | Set Project Start Timecode |
| `reaper_set_sync_reference` | `mode: str` | Set Sync Reference Mode |
| `reaper_batch_render_tracks` | `output_dir: str, track_names: list, format: str` | Batch Render Tracks |
aper_render_stems` | `output, stem_type` | Render St `reaper_create_track` | ` str, count: | Create ADR Track Group `reaper_create_foley_tracks` | Foley Track Group |
| `reaper_create_sound` | None Sound Effects Track Group `reaper_get_video_info` | None | Get| `reaper_insert_cue_marker` |: float, name: str, color: | Insert Cue Marker `reaper_export_session_info` | `file_path: str` | Export Session Info |
### Waveform Generation Operations
| Tool Name | Description |
------|------|
|aper_generate_sine | `frequency: duration: float_rate: int, amplitude: float` | Generate |
| `reaper_generate_square_wave` | `frequency: float, duration: float, sample_rate: int, amplitude: float` | Generate Square Wave |
| `reaper_generate_triangle_wave` | `frequency: float, duration: float, sample_rate: int, amplitude: float` | Generate Triangle Wave |
| `reaper_generate_sawtooth_wave` | `frequency duration: float, sample_rate: int, amplitude: float` | Generate Sawtooth Wave |
| `reaper_generate_noise` | `duration: float, sample_rate: int, amplitude: float, noise_type: str` | Generate Noise |
| `reaper_generate_chord` | `chord_notes: list, duration: float, sample_rate: int, amplitude: float` | Generate Chord |
## Error Handling Mechanism
### Error Type Description
When an operation fails, the tool returns a detailed error message to help diagnose the issue:
| Error Type | Description | Typical Scenarios |
|---------|------|---------|
| `ReaperConnectionError` | Unable to connect to Reaper | Reaper not launched, external script control not enabled |
| `TrackNotFound | Track not found | Track name misspelled, track does not exist |
| `ItemNotFoundError` | Item not found | Item index out of range |
| `FXNotFoundError` | FX plugin not found | Plugin not installed, index error |
| `InvalidParameterError` | Invalid parameter | Parameter value out of range, type error |
| `ReaperFileNotFoundError` | File not found | File path incorrect, file deleted |
| `OperationFailedError` | Operation failed | Unknown error occurred during execution |
### Error Response Example
```json
{
"success": false,
"error_type": "TrackNotFoundError",
"error": "Track 'Vocals' not found",
"detail": "Track 'Vocals' does not exist in the current project",
"suggestion": "Available tracks: ['Track 1', 'Track 2', 'Drums']"
}
```
## Usage Examples
### Example 1: Create Track and Import Audio
```python
# Create track
reaper_add_track("Vocals")
volume
reaper_volume_db("Voc -3.0 audio
reaper_insert_audio_to_track(" "C:/audio/vocal_recording.wav.0)
2: Processing
```python
# Add ReaEQ plugin
reaper_add_reaeq("Vocals")
# Set band parameters
reaperaeq_band("Vocals", 0, 100, -3.0, 1.0, "lowcut") cut
reaper_set_reaeq_band("Vocals", 1, 2500, 0, 1.5, "peak") # Mid frequency boost
reaper_set_reaeq_band("Vocals", 2, 8000,.0, 1.0, "high") # High frequency boost
```
### Example 3: Generate Waveform and Process
```python
wave
reaper_generate_sine_wave(440.0, 2.0, 44100, 0.5)
# Add compressor
reaper_add_reacomp("Track 1")
reaper_set_reacomp_params("Track 1", -18 4.0, 10.0100.0, 3.0)
```
## Project Structure
```
mcpreaper/
├── main.py # MCP Server Entry
├── ReaperProject/ # Test Project and Resources (including testreaper.rpp / testreaper.wav / testmcp.png)
├── scripts/ # Connection Check, Cleanup, Arrangement, and Verification Scripts
├── tools/
│ ├── __init__.py
│ ├── track_tools.py # Track Operation Tools
│ ├── item_tools.py # Media Item Operation Tools
│ ├── playback_tools.py # Playback Control Tools
│ ├── fx_tools.py # FX Plugin Operation Tools
│ ├── marker_tools.py Marker Operation Tools
│ ├── midi_tools # MIDI Basic Operation Tools
│ ├── project # Project Management Tools
│ ├── envelope # Automation Envelope Tools
│ ├── send_tools.py # Track Send Tools
│ ├── render_tools.py # Render and Export Tools
│ ├── midi_ext_tools.py # MIDI Extension Operation Tools
│ ├── audio_tools.py # Audio Processing Tools
│ ├── eq_tools.py # EQ/DSP Processing Tools
│ ├── film_tools.py # Film and Sound Production Tools
│ └── generate_tools.py # Waveform Generation Tools
/
│ ├── __init__.py
│ ├── reaper_client.py # Reaper Client Utility Class
│ └── error_handler.py # Unified Error Handling Module
├── WAV/ # Generated WAV File Directory (created automatically)
├── plots/ # Generated Chart Directory (created automatically)
├── README.md
└── .gitignore
```
### Current Available Scripts
Common scripts are located in `scripts/`, for example:
- `check_reaper_connection.py`: Check Reaper connection and current project information
- `check_web_2307.ps1`: Check Reaper Web Interface (2307) connectivity
- `compose_final.py`: Test project orchestration script
- `validate_all_apis.py`: Batch validate MCP interface availability
Example:
```bash
.venv\Scripts\python.exe scripts\check_reaper_connection.py
```
---
## LLM Client Configuration Guide
The following are detailed steps for configuring the MCP service in various mainstream LLM clients, with all configuration methods sourced from official documentation.
### Prerequisites
1. Ensure the installation steps for this project have been completed.
2. Ensure Reaper has been launched and external script control is enabled.
3. Ensure the virtual environment has been activated.
### 1. CherryStudio
Official Documentation: https://docs.cherry-ai.com/docs/en-us/advanced-basic/mcp
**Method 1: Graphical Interface Configuration**
1. Open CherryStudio
2. Click on the bottom left corner **「Settings」**
3. Enter the **「MCP Server」** tab
4. Click on the top right corner **「Add」** → Select **「Import from JSON」**
5. Paste the following JSON configuration:
```json
{
"mcpServers": {
"mcpreaper": {
"command": "python",
"args": ["C:/path/to/mcpreaper/main.py"],
"env": {}
}
}
}
```
6. Replace `C:/path/to/mcpreaper/main.py` with your actual path (using forward slashes)
7. Click **「OK」**
8. Click the switch to enable the server
**Method 2: Using a Virtual Environment**
```json
{
"mcpServers": {
"mcpreaper": {
"command": "python",
"args": ["-m", "venv", ".venv", "&&", "python", "main.py"],
"env": {},
"cwd": "C:/path/to/mcpreaper"
}
}
}
```
**Usage**: Click the MCP button at the bottom of the chat interface, select the `mcpreaper` service.
**Verification**:
- **Interface Verification**: After configuration, the server status displays green ✅, and the loaded tool list can be seen when expanded.
- **Command Line Test** (verify Python path before startup):
```bash
python C:/path/to/mcpreaper/main.py --help
```
- **Conversation Test**: Input `帮我获取Reaper项目中的所有音轨` in the chat.
---
### 2. WorkBuddy
Official Documentation: https://cloud.tencent.cn/developer/article/2701462
**Method 1: Visual Interface Configuration**
1. In the CodeBuddy IDE sidebar, click on the conversation panel's top right corner `CodeBuddy Settings` gear icon.
2. In the settings interface, switch to the **MCP** tab.
3. Click the right-side `Add MCP` button.
4. Paste the following JSON configuration:
```json
{
"mcpServers": {
"mcpreaper": {
"type": "stdio",
"command": "python",
"args": ["C:/path/to/mcpreaper/main.py"],
"env": {},
"description": "Reaper audio editor control MCP service"
}
}
}
```
5. Click the `Try to Run` button to verify the configuration.
**Method 2: Manually Editing Configuration File**
Configuration file path: `~/.workbuddy/mcp.json` (Windows: `C:\Users\YourUsername\.workbuddy\mcp.json`)
```json
{
"mcpServers": {
"mcpreaper": {
"type": "stdio",
"command": "python",
"args": ["C:/path/to/mcpreaper/main.py"],
"env": {}
}
}
}
```
**Verification**:
- **Interface Verification**: Click the `Try to Run` button, and a green light indicates successful configuration.
- **Command Line Test**:
```bash
python C:/path/to/mcpreaper/main.py --help
```
- **Conversation Test**: Input `帮我获取Reaper项目中的所有音轨` in the chat.
---
### 3. TRAE IDE
Official Documentation: https://docs.trae.ai/ide/add-mcp-servers
**Method 1: Add from MCP Market**
1. In the IDE mode interface, click on the top right corner **Settings** icon.
2. In the left navigation bar, select **MCP**.
3. Click **Add** → **Add from Market**.
4. Search for and find mcpreaper (if published).
**Method 2: Manual Configuration**
1. Click **Add** → **Manual Add**.
2. Fill in the following JSON configuration:
```json
{
"mcpServers": {
"mcpreaper": {
"command": "python",
"args": ["C:/path/to/mcpreaper/main.py"],
"env": {}
}
}
}
```
**Method 3: Project-Level Configuration**
Create `.trae/mcp.json` in the project root directory:
```json
{
"mcpServers": {
"mcpreaper": {
"command": "python",
"args": ["${workspaceFolder}/main.py"],
"env": {}
}
}
}
```
**Verification**:
- **Interface Verification**: The MCP list server status displays green ✅.
- **Command Line Test**:
```bash
python C:/path/to/mcpreaper/main.py --help
```
- **Conversation Test**: Input `帮我获取Reaper项目中的所有音轨` in AI chat.
- **Project-Level Verification**: Ensure **Settings > MCP** has **Enable project-level MCP** switch turned on.
---
### 4. Claude Code
Official Documentation: https://code.claude.com/docs/en/mcp-quickstart
**Method 1: CLI Command Configuration**
Run in terminal:
```bash
claude mcp add mcpreaper -- python C:/path/to/mcpreaper/main.py
```
**Method 2: Edit Configuration File**
Configuration file path: `~/.claude.json` (project-level) or `~/.claude/config.json` (global)
```json
{
"mcpServers": {
"mcpreaper": {
"command": "python",
"args": ["C:/path/to/mcpreaper/main.py"],
"env": {}
}
}
}
```
**Method 3: HTTP Server Mode**
If your MCP service is exposed through HTTP (need to modify main.py to support HTTP):
```bash
claude mcp add --transport http mcpreaper http://localhost:8000/mcp
```
**Verification**:
- **CLI Verification**:
```bash
claude mcp list
```
- **Command Line Test** (verify Python path before startup):
```bash
python C:/path/to/mcpreaper/main.py --help
```
- **Conversation Test**: Input `帮我获取Reaper项目中的所有音轨` in Claude Code chat.
- **Configuration File Verification**: Check if the configuration is written correctly
```bash
# Windows
type %USERPROFILE%\.claude.json
# macOS/Linux
cat ~/.claude.json
```
---
### 5. VS Code
Official Documentation: https://code.visualstudio.com/docs/copilot/customization/mcp-servers
**Method 1: Using Continue Extension**
1. Install Continue extension: https://marketplace.visualstudio.com/items?itemName=Continue.continue
2. Edit Continue configuration file `~/.continue/config.yaml`:
```yaml
mcpServers:
- name: mcpreaper
command: python
args:
- C:/path/to/mcpreaper/main.py
```
**Method 2: Using VS Code Built-in MCP Configuration**
1. Open Command Palette (Ctrl+Shift+P)
2. Run `MCP: Open User Configuration`
3. Add in `mcp.json` file:
```json
{
"mcpServers": {
"mcpreaper": {
"command": "python",
"args": ["C:/path/to/mcpreaper/main.py"],
"env": {}
}
}
}
```
**Method 3: Project-Level Configuration**
Add configuration in `.vscode/mcp.json`:
```json
{
"servers": {
"mcpreaper": {
"type": "stdio",
"command": "${workspaceFolder}/.venv/Scripts/python.exe",
"args": ["${workspaceFolder}/main.py"],
"cwd": "${workspaceFolder}",
"env": {
"REAPER_WEB_PORT": "2307",
"PYTHONIOENCODING": "utf-8",
"PYTHONUTF8": "1"
}
}
}
}
```
**Verification**:
- **Continue Extension Verification**: Open Continue chat, input `/tools` to see tool list.
- **VS Code Built-in Verification**: Open Command Palette (Ctrl+Shift+P), run `MCP: List Servers`.
- **Command Line Test**:
```bash
python C:/path/to/mcpreaper/main.py --help
```
- **Conversation Test**: Input `帮我获取Reaper项目中的所有音轨` in AI chat.
---
### 6. Chat Box
Official Documentation: https://docs.chatboxai.app/guides/mcp.md
**Method 1: Graphical Interface Configuration**
1. Open Chat Box
2. Enter **Settings - MCP** page
3. Click **「Add Server」**
4. Manual configuration:
- Name: `mcpreaper`
- Command: `python`
- Parameters: `C:/path/to/mcpreaper/main.py`
**Method 2: One-Click Installation Link**
Generate one-click installation link:
1. Create configuration JSON:
```json
{
"name": "mcpreaper",
"command": "python",
"args": ["C:/path/to/mcpreaper/main.py"],
"env": {}
}
```
2. Base64 encode configuration
3. Generate link: `chatbox://mcp/install?server=BASE64_ENCODED_CONFIG`
**Verification**:
- **Interface Verification**: On **Settings - MCP** page, view server status, green indicates normal.
- **Command Line Test**:
```bash
python C:/path/to/mcpreaper/main.py --help
```
- **Conversation Test**: Input `帮我获取Reaper项目中的所有音轨` in chat.
---
### 7. Codex CLI
Official Documentation: https://codex.danielvaughan.com/2026/05/19/codex-cli-mcp-server-management-cli-commands-oauth-streamable-http-production-patterns/
**Method 1: CLI Command Configuration**
```bash
codex mcp add mcpreaper -- python C:/path/to/mcpreaper/main.py
```
**Method 2: Edit config.toml**
Configuration file path: `~/.codex/config.toml`
```toml
[mcp_servers.mcpreaper]
command = "python"
args = ["C:/path/to/mcpreaper/main.py"]
enabled = true
[mcp_servers.mcpreaper.env]
# Optional: add environment variables
```
**Method 3: Project-Level Configuration**
Create `.codex/config.toml` in project root directory:
```toml
[mcp_servers.mcpreaper]
command = "python"
args = ["${workspaceFolder}/main.py"]
enabled = true
```
**Verification**:
- **CLI Verification**:
```bash
codex mcp list
```
- **Command Line Test** (verify Python path before startup):
```bash
python C:/path/to/mcpreaper/main.py --help
```
- **Conversation Test**: Input `帮我获取Reaper项目中的所有音轨` in Codex session.
- **Configuration File Verification**: Check if configuration is written correctly
```bash
# Windows
type %USERPROFILE%\.codex\config.toml
# macOS/Linux
cat ~/.codex/config.toml
```
---
### 8. Cursor
Official Documentation: https://cursor.com/docs/mcp
**Method 1: Global Configuration**
Configuration file path: `~/.cursor/mcp.json` (Windows: `%APPDATA%/Cursor/mcp.json`)
```json
{
"mcpServers": {
"mcpreaper": {
"command": "python",
"args": ["C:/path/to/mcpreaper/main.py"],
"env": {}
}
}
}
```
**Method 2: Project-Level Configuration**
Create `.cursor/mcp.json` in project root directory:
```json
{
"mcpServers": {
"mcpreaper": {
"command": "python",
"args": ["${workspaceFolder}/main.py"],
"env": {}
}
}
}
```
**Method 3: Graphical Configuration**
1. Open Cursor Settings
2. Search **MCP**
3. In **MCP Tools** section, click **New MCP Server**
4. Paste configuration and save
**Environment Variable Support**:
Cursor supports configuration interpolation:
```json
{
"mcpServers": {
"mcpreaper": {
"command": "${env:PYTHON_PATH}",
"args": ["${workspaceFolder}/main.py"],
"env": {
"PYTHONPATH": "${workspaceFolder}"
}
}
}
}
```
**Verification**:
- **Interface Verification**: In **Cursor Settings > Tools & Integrations > MCP Tools**, view server status, green indicates normal.
- **Command Line Test**:
```bash
python C:/path/to/mcpreaper/main.py --help
```
- **Conversation Test**: Open Cursor chat (Ctrl+L), input `帮我获取Reaper项目中的所有音轨`.
- **Configuration File Verification**: Check if configuration file is written correctly
```bash
# Windows - View global configuration
type %APPDATA%\Cursor\mcp.json
# Windows - View project configuration
type .cursor\mcp.json
# macOS/Linux - View global configuration
cat ~/.cursor/mcp.json
# macOS/Linux - View project configuration
cat .cursor/mcp.json
```
---
### General Configuration Points
#### Windows Path Precautions
In JSON configuration, Windows paths have two writing methods:
- Use forward slashes: `C:/path/to/mcpreaper/main.py`
- Use double backslashes: `C:\\path\\to\\mcpreaper\\main.py`
#### Virtual Environment Activation
If using a virtual environment, ensure to use the correct Python path:
```json
{
"mcpServers": {
"mcpreaper": {
"command": "C:/path/to/mcpreaper/.venv/Scripts/python.exe",
"args": ["C:/path/to/mcpreaper/main.py"],
"env": {}
}
}
}
```
#### Configuration Verification
After adding configuration, it is recommended to verify the server is running normally:
1. Check server status indicator (green indicates normal).
2. Try calling tools in conversation: `帮我获取Reaper项目中的所有音轨`
3. View tool list to see if all `reaper_*` tools are included.
---
## Troubleshooting
### Frequently Asked Questions
**Q: Failed to connect to Reaper**
A: Please ensure:
1. Reaper is launched and running
2. External script control is enabled (Options → Preferences → Control/OSC/web → ReaScript)
3. Script execution is set to Allow all
4. Python version is 3.11 (REAPER 7.73 does not support 3.14)
**Q: Extension not supported: "py"**
A: REAPER's ReaScript Python is not properly configured. Please check:
1. `Options → Preferences → Plug-ins → ReaScript`
2. Confirm **Enable Python for use with ReaScript** is checked
3. **Custom path to Python dll directory** is set to the directory containing `python311.dll`
4. Example: `D:\Program Files\Python311`
5. Restart Reaper
**Q: reapy import gets stuck / import reapy unresponsive**
A: Common causes and solutions:
1. Confirm `scripts/enable_reapy_server.lua` has been executed in Reaper.
2. Run the check script: `powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\check_web_2307.ps1`
3. If the port is not accessible, check if Web Interface is listening on `2307`.
4. Try running: `MCP: Restart Server (mcpreaper)`
**Q: VS Code MCP displays "mcpreaper failed to start"**
A: Troubleshooting steps:
1. Confirm the configuration format is `"servers"` (not `"mcpServers"`) in `%APPDATA%\Code\User\mcp.json` or `.vscode/mcp.json`
2. Confirm VS Code settings have Copilot MCP enabled: `"chat.mcp.enabled": true`
3. Execute `Developer: Reload Window` to refresh configuration
4. Execute `MCP: List Servers` to view status
**Q: reapy module not found**
A: Ensure the reapy library is installed:
```bash
pip install python-reapy
```
**Q: Invalid argument error**
A: Check if the argument value is within the valid range; error responses will contain hints on valid ranges.
**Q: Track not found**
A: Use `reaper_get_all_track_names` to get all track names in the current project and confirm the track name is spelled correctly.
**Q: Rendering failed**
A: Check if the output path is correct and ensure the output directory exists and has write permissions.
---
## Project Description
- This repository focuses on Reaper's MCP tool capabilities, covering tracks, media items, FX, MIDI, rendering, and film and television sound production workflows.
- The connection strategy has been unified to a single path: Reaper Web Interface port `2307`.
- `ReaperProject/` has been replaced with the test project `testreaper` for verifying orchestration and rendering links.
---
## Contact Information
- yangcan@bfa.edu.cn
---
## License
MIT License
---
## Contribution
Feel free to submit issues and pull requests!
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available