ardour/doc/ardour-mcp-integration.md

Ardour-MCP Integration Guide

Overview

The ardour-mcp project provides a Model Context Protocol (MCP) server that enables AI assistants (such as Claude) to control and interact with Ardour through its Open Sound Control (OSC) interface. This creates a powerful workflow where AI can help with audio production tasks, automation, mixing, and session management.

What is MCP?

Model Context Protocol (MCP) is an open protocol that allows AI assistants to safely interact with external systems through well-defined interfaces. The ardour-mcp server acts as a bridge between Claude (or other MCP-compatible AI assistants) and Ardour's OSC control surface.

Why Use Ardour with MCP?

Benefits

1. AI-Assisted Mixing: Get AI help with EQ suggestions, compression settings, and mix balance
2. Automated Workflows: Automate repetitive tasks like track setup, routing, and plugin configuration
3. Natural Language Control: Control Ardour using conversational commands instead of clicking through menus
4. Session Analysis: Get insights about your session structure, track counts, routing complexity
5. Learning Assistant: Learn Ardour features through interactive guidance
6. Scripting Help: Generate Lua scripts for custom automation
7. Documentation Access: Quick access to Ardour documentation and best practices

Use Cases

• Quick Mix Setup: "Set up a standard rock band mix with drums, bass, guitars, and vocals"
• Automation Tasks: "Create a volume fade out on the master bus from bar 64 to bar 68"
• Plugin Management: "Add a compressor to all drum tracks with conservative settings"
• Session Organization: "Show me all tracks that have no input connections"
• Problem Solving: "Why am I getting feedback in my monitoring setup?"
• Export Automation: "Export all tracks as individual stems with specific naming"

Architecture

┌─────────────────┐
│  Claude Code /  │
│   AI Assistant  │
└────────┬────────┘
         │ MCP Protocol
         │
┌────────▼────────┐
│  ardour-mcp     │
│  MCP Server     │
└────────┬────────┘
         │ OSC Protocol (UDP)
         │ Port 3819
┌────────▼────────┐
│     Ardour      │
│  OSC Surface    │
└─────────────────┘

Prerequisites

System Requirements

• Ardour 8.x or later (built from source recommended for development)
• Python 3.8+ (for ardour-mcp server)
• Network connectivity (localhost for typical setup)
• Just command runner (optional, but recommended)

Installing Dependencies

# Install just (command runner)
curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash

# Or via package manager
# Ubuntu/Debian: cargo install just
# macOS: brew install just
# Arch: pacman -S just

Setup Instructions

Step 1: Build Ardour with OSC Support

Ardour's OSC support is typically enabled by default, but you can explicitly configure it:

# Navigate to Ardour source directory
cd /path/to/ardour

# Configure with OSC support
just configure-osc

# Build Ardour
just build

# Verify OSC library was built
just check-osc

Step 2: Enable OSC in Ardour

1. Start Ardour:

   just run-osc-debug
   

2. Enable OSC Control Surface:

   • Go to Edit > Preferences > Control Surfaces
   • Check the box next to Open Sound Control (OSC)
   • Click Show Protocol Settings

3. Configure OSC Settings:

   • Port: 3819 (default, recommended)
   • Protocol: UDP
   • Reply Mode: Enable if you want feedback from Ardour
   • Bank Size: Set according to your needs (typically 0 for unlimited)

4. Advanced Settings (optional):

   • Debug Mode: Enable for troubleshooting
   • Default Strip Types: Configure which track types to expose
   • Feedback: Configure which parameters send updates

5. Click OK to save settings

Step 3: Set Up ardour-mcp Server

# Navigate to ardour-mcp directory (sibling to ardour)
cd /path/to/ardour-mcp

# Install dependencies (if using Python)
pip install -r requirements.txt

# Or if using Node.js
npm install

# Configure MCP server (check ardour-mcp documentation)
# Typically involves setting OSC host and port

# Start the MCP server
# (refer to ardour-mcp specific instructions)

Step 4: Connect Claude Code to MCP

1. Configure MCP in Claude Code:

   • Create or edit ~/.config/claude-code/mcp_settings.json
   • Add ardour-mcp server configuration

2. Example MCP Configuration:

   {
     "mcpServers": {
       "ardour": {
         "command": "python",
         "args": ["/path/to/ardour-mcp/server.py"],
         "env": {
           "ARDOUR_OSC_HOST": "127.0.0.1",
           "ARDOUR_OSC_PORT": "3819"
         }
       }
     }
   }
   

3. Restart Claude Code to load the MCP server

Step 5: Test the Connection

1. Verify OSC Port:

   just test-osc-connection
   

2. Test from Claude:

   • Open Claude Code
   • Try a simple command: "What tracks are in my current Ardour session?"
   • Claude should use the MCP server to query Ardour via OSC

OSC Protocol Reference

Common OSC Messages

Ardour's OSC implementation supports hundreds of commands. Here are some commonly used ones:

Transport Control

/transport_play          - Start playback
/transport_stop          - Stop playback
/rewind                  - Rewind to start
/ffwd                    - Fast forward to end
/goto_start              - Jump to session start
/goto_end                - Jump to session end

Track/Strip Control

/strip/gain <ssid> <value>              - Set track gain
/strip/pan_stereo_position <ssid> <pos> - Set pan position
/strip/mute <ssid> <0|1>                - Mute/unmute track
/strip/solo <ssid> <0|1>                - Solo/unsolo track
/strip/recenable <ssid> <0|1>           - Enable/disable recording

Session Information

/session/list            - List all tracks
/strip/list              - Get strip list with details
/session/frame_rate      - Get sample rate
/session/timecode        - Get current timecode

Plugin Control

/strip/plugin/parameter <ssid> <plugin> <param> <value>

OSC Query and Feedback

Ardour can send feedback about parameter changes:

/strip/gains             - Subscribe to gain changes for all strips
/strip/fader/<ssid>      - Feedback when fader moves

Development Workflow

Quick Start Development Cycle

# Terminal 1: Build and run Ardour with OSC debugging
cd /path/to/ardour
just osc-dev

# Terminal 2: Run ardour-mcp server
cd /path/to/ardour-mcp
# (start your MCP server)

# Terminal 3: Use Claude Code
claude-code

Monitoring OSC Traffic

1. Enable OSC Debug in Ardour:

   ARDOUR_DEBUG=OSC just run
   

2. Watch Ardour Logs:

   just watch-logs
   

3. Use OSC Monitor Tools:

   • oscdump - Command-line OSC monitor
   • OSCulator (macOS) - GUI OSC monitor and router
   • protokol - Cross-platform OSC/MIDI monitor

Testing OSC Commands Manually

You can test OSC commands using various tools:

# Using oscsend (from liblo-tools)
oscsend localhost 3819 /transport_play

# Using Python with python-osc
python3 << EOF
from pythonosc import udp_client
client = udp_client.SimpleUDPClient("127.0.0.1", 3819)
client.send_message("/transport_play", [])
EOF

Troubleshooting

OSC Not Responding

1. Check OSC is enabled:

   • Edit > Preferences > Control Surfaces
   • Verify "Open Sound Control (OSC)" is checked

2. Verify port is not in use:

   netstat -an | grep 3819
   # or
   lsof -i :3819
   

3. Check firewall settings:

   # Allow UDP port 3819 on localhost
   sudo ufw allow 3819/udp
   

4. Test with debug output:

   ARDOUR_DEBUG=OSC just run
   

MCP Server Connection Issues

1. Verify MCP server is running:

   ps aux | grep ardour-mcp
   

2. Check MCP server logs (location depends on ardour-mcp implementation)

3. Verify Claude Code MCP configuration:

   cat ~/.config/claude-code/mcp_settings.json
   

4. Test MCP server independently (without Claude)

Performance Issues

1. Reduce OSC feedback:

   • Disable unnecessary feedback in OSC settings
   • Use targeted queries instead of broad subscriptions

2. Adjust OSC update rates in Ardour preferences

3. Use local connections only (127.0.0.1, not 0.0.0.0)

Security Considerations

Network Exposure

• Default configuration: OSC listens on localhost only (127.0.0.1)
• Remote access: Be cautious enabling remote OSC access
• Firewall: Keep port 3819 blocked from external networks
• No authentication: OSC has no built-in authentication

Best Practices

1. Never expose OSC to untrusted networks
2. Use SSH tunneling for remote access if needed
3. Run ardour-mcp and Ardour on the same machine
4. Keep ardour-mcp updated for security patches
5. Monitor OSC traffic in production environments

Advanced Topics

Custom OSC Scripts

You can create custom OSC interaction scripts:

# Example: Automated mixing script
from pythonosc import udp_client

client = udp_client.SimpleUDPClient("127.0.0.1", 3819)

# Set consistent levels for drum bus
drum_tracks = [1, 2, 3, 4]  # Kick, snare, toms, OH
for track in drum_tracks:
    client.send_message(f"/strip/gain", [track, -6.0])
    client.send_message(f"/strip/solo", [track, 0])

Integrating with Lua Scripts

Ardour's Lua scripting can complement OSC control:

• Use OSC for external control and monitoring
• Use Lua for complex internal automation
• Combine both for powerful workflows

Multiple OSC Clients

Ardour can handle multiple OSC clients simultaneously:

• Different control surfaces
• Monitoring tools
• Multiple MCP servers
• Mix and match control paradigms

Resources

Documentation

• Ardour OSC Manual
• OSC Protocol Specification
• Ardour Development Guide

Community

• Ardour Forums: https://discourse.ardour.org/
• Ardour IRC: #ardour on libera.chat
• GitHub Issues: https://github.com/Ardour/ardour

Example Projects

• TouchOSC templates for Ardour
• Open Stage Control layouts
• Ardour OSC Python examples in share/scripts/

Contributing

If you develop useful MCP tools or workflows:

1. Share your OSC command patterns
2. Contribute to ardour-mcp documentation
3. Create example sessions/templates
4. Write tutorials and blog posts
5. Report bugs and enhancement requests

Appendix: Complete Setup Checklist

• Ardour built from source with OSC support
• Just command runner installed
• Ardour running: just run-osc-debug
• OSC enabled in Ardour preferences
• OSC port 3819 confirmed open: just test-osc-connection
• ardour-mcp server installed and configured
• ardour-mcp server running
• Claude Code MCP settings configured
• Test connection from Claude successful
• OSC debug output visible in Ardour logs
• Ready to use AI-assisted audio production!

Quick Reference

# Complete setup in one command
just setup-mcp

# Get OSC information
just osc-info

# Get MCP integration information
just mcp-info

# Run Ardour with OSC debugging
just run-osc-debug

# Test OSC connection
just test-osc-connection

# Watch Ardour logs
just watch-logs

---

Last Updated: 2025-11-06 Ardour Version: 8.x OSC Protocol Version: 1.0