Content
# Ardour MCP Server
A Model Context Protocol (MCP) server that provides programmatic control over Ardour DAW through OSC (Open Sound Control). This server enables AI-assisted music production workflows by allowing external applications to control Ardour sessions, tracks, transport, and more.
## Features
### Session Management
- Get session information (name, tempo, time signature, track count)
- Save sessions
- Transport control (play, stop, record, locate)
### Track Operations
- Create audio and MIDI tracks
- Get track information (name, volume, mute, solo status)
- Set track properties (name, volume, mute, solo, record enable)
### Transport Control
- Start/stop playback and recording
- Set tempo
- Jump to specific time positions
- Get transport state information
### Recording
- Enable/disable recording on tracks
- Start recording with transport
## Prerequisites
- **Ardour DAW** (version 5.0 or later) installed and running
- **Python 3.10+**
- **UV package manager** (recommended) or pip
## Installation
### 1. Clone or Download
If you have this as a git repository:
```bash
git clone <repository-url>
cd ardour-mcp
```
### 2. Install Dependencies
Using UV (recommended):
```bash
uv sync
```
Using pip:
```bash
pip install -e .
```
### 3. Configure Ardour OSC
1. Open Ardour
2. Go to **Edit → Preferences** (or **Ardour → Preferences** on macOS)
3. Navigate to **Control Surfaces**
4. Enable **Open Sound Control (OSC)**
5. Click **Show Protocol Settings**
6. Configure the following settings:
- **OSC Server Port**: `3819` (default)
- **Reply Port**: `9000` (or any available port)
- **Bank Size**: `0` (for unlimited)
- **Send Page Size**: `0`
- **Plugin Page Size**: `0`
- **Gain Mode**: `dB`
- **Debug Mode**: Enable for troubleshooting (optional)
7. Click **OK** and restart Ardour
## Usage
### Running the MCP Server
Using UV:
```bash
uv run MCP_Server/server.py
```
Using Python directly:
```bash
python -m MCP_Server.server
```
### Adding to Cline MCP Configuration
Add the following entry to your `cline_mcp_settings.json`:
```json
{
"mcpServers": {
"github.com/snakkrz/ardour-mcp": {
"command": "uv",
"args": [
"run",
"--directory",
"/home/snakkrz/Code/Projects/ardour-mcp",
"MCP_Server/server.py"
],
"disabled": false,
"autoApprove": []
}
}
}
```
## Available Tools
### Session Information
- `get_session_info()` - Get current session details
- `get_transport_info()` - Get transport state
- `save_session()` - Save the current session
### Transport Control
- `start_playback()` - Start playing
- `stop_playback()` - Stop playing
- `start_recording()` - Start recording
- `set_tempo(tempo)` - Set session tempo in BPM
- `goto_position(position)` - Jump to time position in seconds
### Track Management
- `get_track_info(track_index)` - Get track information
- `create_track(track_type, name)` - Create new audio/MIDI track
- `set_track_name(track_index, name)` - Rename track
- `set_track_volume(track_index, volume)` - Set track volume (0.0-1.0)
- `set_track_mute(track_index, mute)` - Mute/unmute track
- `set_track_solo(track_index, solo)` - Solo/unsolo track
- `record_enable(track_index, enable)` - Enable/disable recording
## Example Usage
```python
# Get session information
session_info = get_session_info()
# Create a new MIDI track
create_track("midi", "Lead Synth")
# Set tempo to 128 BPM
set_tempo(128.0)
# Start playback
start_playback()
# Create and configure an audio track
create_track("audio", "Vocals")
set_track_volume(2, 0.8) # Set track 2 volume to 80%
record_enable(2, True) # Enable recording on track 2
# Start recording
start_recording()
```
## Troubleshooting
### Connection Issues
1. **"Could not connect to Ardour"**
- Ensure Ardour is running
- Verify OSC is enabled in Ardour preferences
- Check that port 3819 is not blocked by firewall
- Try restarting Ardour after enabling OSC
2. **"OSC communication error"**
- Verify Ardour OSC settings match server configuration
- Check Ardour's OSC debug output for error messages
- Ensure no other applications are using the OSC ports
3. **"No response from Ardour"**
- Increase timeout values in the server code
- Check Ardour's OSC feedback settings
- Verify the receive port (9000) is available
### Debugging
Enable debug logging by setting the log level:
```python
logging.getLogger("ArdourMCPServer").setLevel(logging.DEBUG)
```
Check Ardour's OSC debug output in the application logs or console.
## Architecture
The server uses OSC (Open Sound Control) to communicate with Ardour:
- **OSC Client**: Sends commands to Ardour (port 3819)
- **OSC Server**: Receives feedback from Ardour (port 9000)
- **MCP Framework**: Provides tools interface for external applications
## Comparison with Ableton MCP
| Feature | Ardour MCP | Ableton MCP |
|---------|------------|-------------|
| Communication | OSC | Custom Socket |
| Session Model | Linear Timeline | Session View + Arrangement |
| Track Types | Audio/MIDI | Audio/MIDI/Return |
| Plugin Control | OSC Parameters | Live API |
| Audio Import | File-based | File + Live Browser |
| Real-time | Full Support | Full Support |
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request
## License
MIT License - see LICENSE file for details.
## Acknowledgments
- Inspired by the [Ableton MCP Server](https://github.com/ahujasid/ableton-mcp)
- Built with the [Model Context Protocol](https://github.com/modelcontextprotocol)
- Uses [python-osc](https://github.com/attwad/python-osc) for OSC communication
