Skip to content
Back to search

reaper-reapy-mcp

Reaper and MCP or AI integration A Python application for controlling REAPER Digital Audio Workstation (DAW) using the MCP(Model context protocol).

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/wegitor--reaper-reapy-mcp/badge.svg)](/listings/wegitor--reaper-reapy-mcp)

HTML

<a href="/listings/wegitor--reaper-reapy-mcp"><img src="/api/listings/wegitor--reaper-reapy-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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:

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

uv --directory <project_path> run -m reaper_reapy_mcp

For the current directory and http MCP mode:

uv --directory . run -m reaper_reapy_mcp --mode http

For example, on Windows:

uv --directory C:\path\to\reaper_reapy_mcp run -m reaper_reapy_mcp

Or using the Python module directly after installation:

python -m reaper_reapy_mcp

HTTP Mode

Run the server in HTTP mode with default settings:

python -m reaper_reapy_mcp --mode http

Run with custom host and port:

python -m reaper_reapy_mcp --mode http --http-host example_host --http-port 3958

Use the MCP inspector to test the tools:

   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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 257 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Reaper and MCP or AI integration
  2. A Python application for controlling REAPER Digital Audio Workstation (DAW) using the MCP(Model context protocol).
  3. ![REAPER MCP MIDI generation Demo](docs/media/midi-generation.gif)
  4. ![REAPER MCP project features Demo](docs/media/reaper-reapy-mcp-demo-for-gif-002.gif)
  5. ## Features
  6. - **Track Management**: Create, rename, and color tracks
  7. - **FX Management**: Add, remove, and control effect parameters
  8. - **Project Control**: Set tempo, manage regions and markers
  9. - **Master Track Control**: Volume, pan, mute, and solo operations
  10. - **MIDI Operations**: Create items, add/get notes, clear items with musical positioning
  11. - **Audio Item Operations**: Insert, duplicate, modify with enhanced positioning support
  12. - **Dual Position Format**: Support both time (seconds) and measure:beat notation
  13. - **Reliable Duplication**: Uses REAPER's built-in commands for accurate item copying
  14. - **MCP Integration**: Model Context Protocol server for AI assistant control
  15. ## Status
  16. - **Checked on Linux**: Yes
  17. - **MCP HTTP Mode**: Supported for parameters
  18. ## Requirements
  19. - Python 3.7+
  20. - REAPER DAW
  21. - `python-reapy` Python module
  22. - `mcp[cli]` package for MCP server
  23. - Internet connection (for downloading sample audio file)
  24. ## Installation
  25. 1. Install REAPER if you haven't already
  26. 2. Enable reapy server via REAPER scripting
  27. add reaper_side_enable_server.py to reaper actions and run it inside reaper studio
  28. 3. Install the package:
  29. ```bash
  30. # From PyPI
  31. pip install reaper_reapy_mcp
  32. # From GitHub repository
  33. pip install git+https://github.com/wegitor/reaper-reapy-mcp.git
  34. ```
  35. 4. Enable python in REAPER
  36. 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.
  37. ### Sample Audio File
  38. The application uses a sample MP3 file for testing audio operations. The file will be automatically downloaded when needed from:
  39. ```
  40. https://www2.cs.uic.edu/~i101/SoundFiles/StarWars3.mp3
  41. ```
  42. This is a short Star Wars theme clip that's commonly used for testing audio applications.
  43. ### Running the Server
  44. You can run the server using uv directly:
  45. ```bash
  46. uv --directory <project_path> run -m reaper_reapy_mcp
  47. ```
  48. For the current directory and http MCP mode:
  49. ```bash
  50. uv --directory . run -m reaper_reapy_mcp --mode http
  51. ```
  52. For example, on Windows:
  53. ```bash
  54. uv --directory C:\path\to\reaper_reapy_mcp run -m reaper_reapy_mcp
  55. ```
  56. Or using the Python module directly after installation:
  57. ```bash
  58. python -m reaper_reapy_mcp
  59. ```
  60. #### HTTP Mode
  61. Run the server in HTTP mode with default settings:
  62. ```bash
  63. python -m reaper_reapy_mcp --mode http
  64. ```
  65. Run with custom host and port:
  66. ```bash
  67. python -m reaper_reapy_mcp --mode http --http-host example_host --http-port 3958
  68. ```
  69. ### Use the MCP inspector to test the tools:
  70. ```bash
  71. test_mcp.bat
  72. ```
  73. Available MCP tools:
  74. #### Track Management
  75. - `test_connection`: Verify connection to REAPER
  76. - `create_track`: Create a new track
  77. - `rename_track`: Rename an existing track
  78. - `set_track_color`: Set track color
  79. - `get_track_color`: Get track color
  80. - `get_track_count`: Get number of tracks in project
  81. - `get_track_list`: Get list of all tracks with their properties
  82. #### FX Management
  83. - `add_fx`: Add an FX to a track
  84. - `remove_fx`: Remove an FX from a track
  85. - `set_fx_param`: Set FX parameter value
  86. - `get_fx_param`: Get FX parameter value
  87. - `get_fx_param_list`: Get list of FX parameters
  88. - `get_fx_list`: Get list of FX on a track
  89. - `get_available_fx_list`: Get list of available FX plugins
  90. - `toggle_fx`: Toggle FX enable/disable state
  91. #### Project Control
  92. - `set_tempo`: Set project tempo
  93. - `get_tempo`: Get current tempo
  94. - `get_time_signature`: Get current time signature
  95. - `set_project_time_signature`: Set project default time signature
  96. - `set_time_signature`: Set time signature at position
  97. - `create_region`: Create a region
  98. - `delete_region`: Delete a region
  99. - `create_marker`: Create a marker
  100. - `delete_marker`: Delete a marker
  101. - `render_project`: Render project to audio file
  102. #### Master Track
  103. - `get_master_track`: Get master track information
  104. - `set_master_volume`: Set master track volume
  105. - `set_master_pan`: Set master track pan
  106. - `toggle_master_mute`: Toggle master track mute
  107. - `toggle_master_solo`: Toggle master track solo
  108. #### MIDI Operations
  109. - `create_midi_item`: Create an empty MIDI item on a track
  110. - Supports both time (seconds) and measure:beat positioning
  111. - `add_midi_note`: Add a MIDI note to a MIDI item
  112. - `add_midi_notes`: Add multiple MIDI notes at once
  113. - `get_midi_notes`: Get all MIDI notes from a MIDI item
  114. - `clear_midi_item`: Clear all MIDI notes from a MIDI item
  115. #### Audio Item Operations
  116. - `insert_audio_item`: Insert an audio file as a media item
  117. - Supports both time (seconds) and measure:beat positioning
  118. - `duplicate_item`: Duplicate an existing item (MIDI or audio)
  119. - Uses REAPER's built-in duplication for reliable copying
  120. - Supports both time (seconds) and measure:beat positioning
  121. - `get_item_properties`: Get properties of a media item
  122. - `set_item_position`: Set the position of a media item
  123. - Supports both time (seconds) and measure:beat positioning
  124. - `set_item_length`: Set the length of a media item
  125. - `delete_item`: Delete a media item
  126. - `get_items_in_time_range`: Get items within a time range
  127. - Supports both time (seconds) and measure:beat positioning
  128. ### Item ID System
  129. 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:
  130. - Item IDs are zero-based indices
  131. - Each track maintains its own sequence of item indices
  132. - Indices are stable until items are deleted or reordered
  133. - All item operations (MIDI, audio, properties) use the same indexing system
  134. ### Position Format Support
  135. Many MCP tools now support dual position formats for enhanced musical workflow:
  136. #### Time Format (seconds)
  137. ```json
  138. {
  139. "start_time": 15.5,
  140. "new_time": 30.0
  141. }
  142. ```
  143. #### Measure:Beat Format
  144. ```json
  145. {
  146. "start_measure": "3:2,500",
  147. "new_measure": "5:1,000"
  148. }
  149. ```
  150. **Format**: `"measure:beat,fraction"` where:
  151. - `measure`: 1-based measure number
  152. - `beat`: 1-based beat number
  153. - `fraction`: milliseconds (000-999) representing fraction of a beat
  154. - Example: `"4:2,500"` = measure 4, beat 2, half beat (500ms)
  155. #### Tools Supporting Both Formats:
  156. - `create_midi_item` - position via `start_time` OR `start_measure`
  157. - `insert_audio_item` - position via `start_time` OR `start_measure`
  158. - `duplicate_item` - position via `new_time` OR `new_measure`
  159. - `set_item_position` - position via `new_time` OR `new_measure`
  160. - `get_items_in_time_range` - range via time OR measure parameters
  161. ### Claude configuration (with uv run):
  162. ```json
  163. {
  164. "mcpServers": {
  165. "reaper-reapy-mcp": {
  166. "type": "stdio",
  167. "command": "uv",
  168. "args": [
  169. "--directory",
  170. "<path to folder>",
  171. "run",
  172. "-m",
  173. "reaper_reapy_mcp"
  174. ]
  175. }
  176. }
  177. }
  178. ```
  179. ### Claude configuration direct:
  180. ```json
  181. {
  182. "mcpServers": {
  183. "reaper-reapy-mcp": {
  184. "type": "stdio",
  185. "command": "python",
  186. "args": [
  187. "-m",
  188. "reaper_reapy_mcp"
  189. ]
  190. }
  191. }
  192. }
  193. ```
  194. or
  195. ```json
  196. {
  197. "mcpServers": {
  198. "reaper-reapy-mcp": {
  199. "type": "stdio",
  200. "command": "python",
  201. "args": [
  202. "<path to folder>\\src\\reaper_reapy_mcp.py"
  203. ]
  204. }
  205. }
  206. }
  207. ```
  208. ## Contributing
  209. Contributions are welcome! Please feel free to submit a Pull Request.
  210. ## License
  211. This project is licensed under the MIT License - see the LICENSE file for details.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.