# REAPER MCP Server
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
- Get project details (BPM, track count, track names)
- Initialize new projects with optional track clearing
- Get project length in seconds
- Save the current project
- Get playback state (playing, paused, stopped, recording)
- Get current play position in seconds
- Get current playback rate
- Get project name and file path
- Check for unsaved changes (dirty status)
- Undo/redo operations with availability checks
- Convert between beats and time (seconds)
### ▶️ Playback Control
- Start, pause, stop playback
- Start recording
- Get/set edit cursor position
- Get/set time selection range
### 🔖 Markers & Regions
- Add markers at specific time positions
- Add regions between start and end times
- List all markers and regions with details
- Get marker and region counts
### 🎚️ Track Operations
- Create tracks at specific indices
- Delete tracks by index
- List all tracks with names
- Get track name by index
- Get track item count by index
- Set track color by index (RGB values)
- Mute/unmute tracks
- Solo/unsolo tracks
- Get/set track volume (0dB = 1.0)
- Get/set track pan (-1.0 to 1.0)
- Select/unselect tracks
### ⏱️ Tempo Control
- Get current project BPM
- Set project BPM (1-960 range)
### 🎹 MIDI Generation & Import
- Add MIDI notes to tracks as new MIDI items
- Generate step-sequenced MIDI patterns
- Create MIDI files with pretty_midi
- Import MIDI files (base64-encoded) onto tracks
### 🎛️ FX & VST Plugins
- List available VST plugins from REAPER configuration
- Add FX/VST plugins to tracks
- List FX on specific tracks
- Get/set FX parameter values (normalized 0-1)
### 🎧 Audio Sample Management
- Configure and manage sample directories (persistent)
- Search for audio samples across directories (WAV, AIFF, FLAC, MP3, OGG)
- Import audio samples to tracks
- Time-stretch samples via playback rate control
## 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 through the reapy bridge. Ensure REAPER is running and reapy is properly configured 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 with Default Settings (stdio transport)
```bash
python -m reaper_mcp
```
### Run with MCP Proxy (stdio)
```bash
uv tool run mcpo --port 8000 -- uv run reaper_mcp
```
### Run with MCP Proxy (HTTP/SSE)
```bash
uv tool run mcpo --port 8000 -- uv run python -m reaper_mcp --transport sse --port 8001
```
### Command-Line Options
```bash
python -m reaper_mcp [OPTIONS]
```
**Available Options:**
- `--transport {stdio,sse,http,ws,websocket}` - Transport protocol (default: `stdio`)
- `--host HOST` - Bind host for network transports (default: `127.0.0.1`)
- `--port PORT` - Bind port for network transports (default: `8000`)
- `--path PATH` - URL path for HTTP/SSE/WebSocket transports
- `--allow-origin ORIGIN` - Allowed CORS origin (can be specified multiple times)
### Examples
**WebSocket server on port 9000:**
```bash
python -m reaper_mcp --transport ws --port 9000
```
**SSE server with custom host:**
```bash
python -m reaper_mcp --transport sse --host 0.0.0.0 --port 8080
```
**stdio mode (for Claude Desktop or other MCP clients):**
```bash
python -m reaper_mcp
```
## Integration with MCP Clients
### Claude Desktop Configuration
Add to your Claude Desktop MCP settings:
```json
{
"mcpServers": {
"reaper": {
"command": "python",
"args": ["-m", "reaper_mcp"]
}
}
}
```
Or with uv:
```json
{
"mcpServers": {
"reaper": {
"command": "uv",
"args": ["run", "python", "-m", "reaper_mcp"]
}
}
}
```
## Development
### Project Structure
```
reaper_mcp/
├── __main__.py # Entry point and CLI
├── mcp_core.py # FastMCP server initialization
├── project.py # Project management tools
├── tracks.py # Track operations
├── tempo.py # Tempo/BPM control
├── midi.py # MIDI generation and import
├── fx.py # FX/VST plugin management
├── samples.py # Audio sample management
└── util.py # Utility functions
```
### Dependencies
- `fastmcp>=2.12.5` - MCP server framework
- `python-reapy>=0.10.0` - REAPER Python API
- `pretty-midi>=0.2.10` - MIDI file generation
## 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
## License
See project repository for license information.
## 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/)
Raw data
{
"_id": null,
"home_page": null,
"name": "reaper-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "audio, daw, mcp, midi, model-context-protocol, music-production, reaper, reapy, vst",
"author": null,
"author_email": "nbdy <me@nbdy.io>",
"download_url": "https://files.pythonhosted.org/packages/bf/3b/ead749def632e3bea23755456cb2c8e6c057f43a7bb53d086b49554b30ec/reaper_mcp-1.2.0.tar.gz",
"platform": null,
"description": "# REAPER MCP Server\n\nA 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.\n\n## Features\n\n### \ud83c\udfb5 Project Management\n- Get project details (BPM, track count, track names)\n- Initialize new projects with optional track clearing\n- Get project length in seconds\n- Save the current project\n- Get playback state (playing, paused, stopped, recording)\n- Get current play position in seconds\n- Get current playback rate\n- Get project name and file path\n- Check for unsaved changes (dirty status)\n- Undo/redo operations with availability checks\n- Convert between beats and time (seconds)\n\n### \u25b6\ufe0f Playback Control\n- Start, pause, stop playback\n- Start recording\n- Get/set edit cursor position\n- Get/set time selection range\n\n### \ud83d\udd16 Markers & Regions\n- Add markers at specific time positions\n- Add regions between start and end times\n- List all markers and regions with details\n- Get marker and region counts\n\n### \ud83c\udf9a\ufe0f Track Operations\n- Create tracks at specific indices\n- Delete tracks by index\n- List all tracks with names\n- Get track name by index\n- Get track item count by index\n- Set track color by index (RGB values)\n- Mute/unmute tracks\n- Solo/unsolo tracks\n- Get/set track volume (0dB = 1.0)\n- Get/set track pan (-1.0 to 1.0)\n- Select/unselect tracks\n\n### \u23f1\ufe0f Tempo Control\n- Get current project BPM\n- Set project BPM (1-960 range)\n\n### \ud83c\udfb9 MIDI Generation & Import\n- Add MIDI notes to tracks as new MIDI items\n- Generate step-sequenced MIDI patterns\n- Create MIDI files with pretty_midi\n- Import MIDI files (base64-encoded) onto tracks\n\n### \ud83c\udf9b\ufe0f FX & VST Plugins\n- List available VST plugins from REAPER configuration\n- Add FX/VST plugins to tracks\n- List FX on specific tracks\n- Get/set FX parameter values (normalized 0-1)\n\n### \ud83c\udfa7 Audio Sample Management\n- Configure and manage sample directories (persistent)\n- Search for audio samples across directories (WAV, AIFF, FLAC, MP3, OGG)\n- Import audio samples to tracks\n- Time-stretch samples via playback rate control\n\n## Prerequisites\n\n- **REAPER** installed with ReaScript enabled\n- **python-reapy** bridge configured for out-of-process control\n- **Python 3.11+**\n\n> **Note:** The server must be able to communicate with REAPER through the reapy bridge. Ensure REAPER is running and reapy is properly configured before starting the server.\n\n## Installation\n\n### Using uv (Recommended)\n\n```bash\n# Install with uv\nuv pip install reaper-mcp\n\n# Or run directly with uv\nuv tool install reaper-mcp\n```\n\n### Using pip\n\n```bash\npip install reaper-mcp\n```\n\n## Usage\n\n### Run with Default Settings (stdio transport)\n\n```bash\npython -m reaper_mcp\n```\n\n### Run with MCP Proxy (stdio)\n\n```bash\nuv tool run mcpo --port 8000 -- uv run reaper_mcp\n```\n\n### Run with MCP Proxy (HTTP/SSE)\n\n```bash\nuv tool run mcpo --port 8000 -- uv run python -m reaper_mcp --transport sse --port 8001\n```\n\n### Command-Line Options\n\n```bash\npython -m reaper_mcp [OPTIONS]\n```\n\n**Available Options:**\n\n- `--transport {stdio,sse,http,ws,websocket}` - Transport protocol (default: `stdio`)\n- `--host HOST` - Bind host for network transports (default: `127.0.0.1`)\n- `--port PORT` - Bind port for network transports (default: `8000`)\n- `--path PATH` - URL path for HTTP/SSE/WebSocket transports\n- `--allow-origin ORIGIN` - Allowed CORS origin (can be specified multiple times)\n\n### Examples\n\n**WebSocket server on port 9000:**\n```bash\npython -m reaper_mcp --transport ws --port 9000\n```\n\n**SSE server with custom host:**\n```bash\npython -m reaper_mcp --transport sse --host 0.0.0.0 --port 8080\n```\n\n**stdio mode (for Claude Desktop or other MCP clients):**\n```bash\npython -m reaper_mcp\n```\n\n## Integration with MCP Clients\n\n### Claude Desktop Configuration\n\nAdd to your Claude Desktop MCP settings:\n\n```json\n{\n \"mcpServers\": {\n \"reaper\": {\n \"command\": \"python\",\n \"args\": [\"-m\", \"reaper_mcp\"]\n }\n }\n}\n```\n\nOr with uv:\n\n```json\n{\n \"mcpServers\": {\n \"reaper\": {\n \"command\": \"uv\",\n \"args\": [\"run\", \"python\", \"-m\", \"reaper_mcp\"]\n }\n }\n}\n```\n\n## Development\n\n### Project Structure\n\n```\nreaper_mcp/\n\u251c\u2500\u2500 __main__.py # Entry point and CLI\n\u251c\u2500\u2500 mcp_core.py # FastMCP server initialization\n\u251c\u2500\u2500 project.py # Project management tools\n\u251c\u2500\u2500 tracks.py # Track operations\n\u251c\u2500\u2500 tempo.py # Tempo/BPM control\n\u251c\u2500\u2500 midi.py # MIDI generation and import\n\u251c\u2500\u2500 fx.py # FX/VST plugin management\n\u251c\u2500\u2500 samples.py # Audio sample management\n\u2514\u2500\u2500 util.py # Utility functions\n```\n\n### Dependencies\n\n- `fastmcp>=2.12.5` - MCP server framework\n- `python-reapy>=0.10.0` - REAPER Python API\n- `pretty-midi>=0.2.10` - MIDI file generation\n\n## Notes\n\n- Tools are designed to be small and focused - prefer calling multiple tools over complex combined actions\n- File paths must be accessible from the REAPER host machine\n- Some operations depend on REAPER configuration, OS, and installed plugins\n- Tools return helpful error messages when operations are unavailable\n\n## License\n\nSee project repository for license information.\n\n## Links\n\n- [REAPER DAW](https://www.reaper.fm/)\n- [FastMCP](https://github.com/jlowin/fastmcp)\n- [python-reapy](https://github.com/RomeoDespres/reapy)\n- [Model Context Protocol](https://modelcontextprotocol.io/)\n",
"bugtrack_url": null,
"license": null,
"summary": "MCP server for REAPER DAW: project, tracks, MIDI, FX, samples.",
"version": "1.2.0",
"project_urls": {
"Homepage": "https://github.com/nbdy/reaper-mcp",
"Issues": "https://github.com/nbdy/reaper-mcp/-/issues",
"Repository": "https://github.com/nbdy/reaper-mcp"
},
"split_keywords": [
"audio",
" daw",
" mcp",
" midi",
" model-context-protocol",
" music-production",
" reaper",
" reapy",
" vst"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4c3f21fae8f339d3ce63ace735da1abc370139f71cb693350fe63e78e9f9146e",
"md5": "27438618cc76ac25d63c123b0fd92992",
"sha256": "36dff1c88d80be6b213c68169c46c4b087f76dea71ea5e49b793e913a4fce3f1"
},
"downloads": -1,
"filename": "reaper_mcp-1.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "27438618cc76ac25d63c123b0fd92992",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 20202,
"upload_time": "2025-10-19T23:03:40",
"upload_time_iso_8601": "2025-10-19T23:03:40.810194Z",
"url": "https://files.pythonhosted.org/packages/4c/3f/21fae8f339d3ce63ace735da1abc370139f71cb693350fe63e78e9f9146e/reaper_mcp-1.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "bf3bead749def632e3bea23755456cb2c8e6c057f43a7bb53d086b49554b30ec",
"md5": "c3e3fd969dae0249a298c641de8ee839",
"sha256": "fd94c72a7f75c46ad0fd2eb2ecc02cdd95c661e5742a38c3c51bc8a171a5a6fb"
},
"downloads": -1,
"filename": "reaper_mcp-1.2.0.tar.gz",
"has_sig": false,
"md5_digest": "c3e3fd969dae0249a298c641de8ee839",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 90378,
"upload_time": "2025-10-19T23:03:42",
"upload_time_iso_8601": "2025-10-19T23:03:42.227910Z",
"url": "https://files.pythonhosted.org/packages/bf/3b/ead749def632e3bea23755456cb2c8e6c057f43a7bb53d086b49554b30ec/reaper_mcp-1.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-19 23:03:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "nbdy",
"github_project": "reaper-mcp",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "reaper-mcp"
}
JSON
