Content
# Reaper and MCP or AI integration
A Python application for controlling REAPER Digital Audio Workstation (DAW) using the MCP(Model context protocol).
## Features
- **Track Management**: Create, rename, and color tracks
- **FX Management**: Add, remove, and control effect parameters
- **Project Control**: Set tempo, manage regions and markers
- **Master Track Control**: Volume, pan, mute, and solo operations
- **MIDI Operations**: Create items, add/get notes, clear items with musical positioning
- **Audio Item Operations**: Insert, duplicate, modify with enhanced positioning support
- **Dual Position Format**: Support both time (seconds) and measure:beat notation
- **Reliable Duplication**: Uses REAPER's built-in commands for accurate item copying
- **MCP Integration**: Model Context Protocol server for AI assistant control
## Requirements
- Python 3.7+
- REAPER DAW
- `python-reapy` Python module
- `mcp[cli]` package for MCP server
- Internet connection (for downloading sample audio file)
## Installation
1. Install REAPER if you haven't already
2. Enable reapy server via REAPER scripting
add reaper_side_enable_server.py to reaper actions and run it inside reaper studio
3. Install the package:
```bash
# From PyPI
pip install reaper_reapy_mcp
# From GitHub repository
pip install git+https://github.com/wegitor/reaper-reapy-mcp.git
```
4. Enable python in REAPER
The wheel package includes all necessary dependencies and can be used in other Python projects that need REAPER integration. The project uses `pyproject.toml` for modern Python packaging configuration, which provides better dependency management and build system configuration.
### Sample Audio File
The application uses a sample MP3 file for testing audio operations. The file will be automatically downloaded when needed from:
```
https://www2.cs.uic.edu/~i101/SoundFiles/StarWars3.mp3
```
This is a short Star Wars theme clip that's commonly used for testing audio applications.
### Running the Server
You can run the server using uv directly:
```bash
uv --directory <project_path> run -m reaper_reapy_mcp
```
For example, on Windows:
```bash
uv --directory C:\path\to\reaper_reapy_mcp run -m reaper_reapy_mcp
```
Or using the Python module directly after installation:
```bash
python -m reaper_reapy_mcp
```
### Use the MCP inspector to test the tools:
```bash
test_mcp.bat
```
Available MCP tools:
#### Track Management
- `test_connection`: Verify connection to REAPER
- `create_track`: Create a new track
- `rename_track`: Rename an existing track
- `set_track_color`: Set track color
- `get_track_color`: Get track color
- `get_track_count`: Get number of tracks in project
- `get_track_list`: Get list of all tracks with their properties
#### FX Management
- `add_fx`: Add an FX to a track
- `remove_fx`: Remove an FX from a track
- `set_fx_param`: Set FX parameter value
- `get_fx_param`: Get FX parameter value
- `get_fx_param_list`: Get list of FX parameters
- `get_fx_list`: Get list of FX on a track
- `get_available_fx_list`: Get list of available FX plugins
- `toggle_fx`: Toggle FX enable/disable state
#### Project Control
- `set_tempo`: Set project tempo
- `get_tempo`: Get current tempo
- `get_time_signature`: Get current time signature
- `set_project_time_signature`: Set project default time signature
- `set_time_signature`: Set time signature at position
- `create_region`: Create a region
- `delete_region`: Delete a region
- `create_marker`: Create a marker
- `delete_marker`: Delete a marker
- `render_project`: Render project to audio file
#### Master Track
- `get_master_track`: Get master track information
- `set_master_volume`: Set master track volume
- `set_master_pan`: Set master track pan
- `toggle_master_mute`: Toggle master track mute
- `toggle_master_solo`: Toggle master track solo
#### MIDI Operations
- `create_midi_item`: Create an empty MIDI item on a track
- Supports both time (seconds) and measure:beat positioning
- `add_midi_note`: Add a MIDI note to a MIDI item
- `add_midi_notes`: Add multiple MIDI notes at once
- `get_midi_notes`: Get all MIDI notes from a MIDI item
- `clear_midi_item`: Clear all MIDI notes from a MIDI item
#### Audio Item Operations
- `insert_audio_item`: Insert an audio file as a media item
- Supports both time (seconds) and measure:beat positioning
- `duplicate_item`: Duplicate an existing item (MIDI or audio)
- Uses REAPER's built-in duplication for reliable copying
- Supports both time (seconds) and measure:beat positioning
- `get_item_properties`: Get properties of a media item
- `set_item_position`: Set the position of a media item
- Supports both time (seconds) and measure:beat positioning
- `set_item_length`: Set the length of a media item
- `delete_item`: Delete a media item
- `get_items_in_time_range`: Get items within a time range
- Supports both time (seconds) and measure:beat positioning
### Item ID System
All item operations use a sequential index system (0..n) for item identification. This makes it easier to work with items in scripts and automation:
- Item IDs are zero-based indices
- Each track maintains its own sequence of item indices
- Indices are stable until items are deleted or reordered
- All item operations (MIDI, audio, properties) use the same indexing system
### Position Format Support
Many MCP tools now support dual position formats for enhanced musical workflow:
#### Time Format (seconds)
```json
{
"start_time": 15.5,
"new_time": 30.0
}
```
#### Measure:Beat Format
```json
{
"start_measure": "3:2,500",
"new_measure": "5:1,000"
}
```
**Format**: `"measure:beat,fraction"` where:
- `measure`: 1-based measure number
- `beat`: 1-based beat number
- `fraction`: milliseconds (000-999) representing fraction of a beat
- Example: `"4:2,500"` = measure 4, beat 2, half beat (500ms)
#### Tools Supporting Both Formats:
- `create_midi_item` - position via `start_time` OR `start_measure`
- `insert_audio_item` - position via `start_time` OR `start_measure`
- `duplicate_item` - position via `new_time` OR `new_measure`
- `set_item_position` - position via `new_time` OR `new_measure`
- `get_items_in_time_range` - range via time OR measure parameters
### Claude configuration (with uv run):
```json
{
"mcpServers": {
"reaper-reapy-mcp": {
"type": "stdio",
"command": "uv",
"args": [
"--directory",
"<path to folder>",
"run",
"-m",
"reaper_reapy_mcp"
]
}
}
}
```
### Claude configuration direct:
```json
{
"mcpServers": {
"reaper-reapy-mcp": {
"type": "stdio",
"command": "python",
"args": [
"-m",
"reaper_reapy_mcp"
]
}
}
}
```
or
```json
{
"mcpServers": {
"reaper-reapy-mcp": {
"type": "stdio",
"command": "python",
"args": [
"<path to folder>\\src\\reaper_reapy_mcp.py"
]
}
}
}
```
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## License
This project is licensed under the MIT License - see the LICENSE file for details.
