README

Ardour MCP 🎵

Model Context Protocol server for Ardour DAW - Control Ardour through AI assistants

The first MCP integration for a major open-source Digital Audio Workstation. Ardour MCP enables natural language control of Ardour through AI assistants like Claude, using the Model Context Protocol.

🎯 What This Does

Ardour MCP allows you to control Ardour using natural language:

• “Start playback in Ardour” → Transport control
• “Create a new audio track called ‘Vocals’” → Track management
• “Set track 1 volume to -6dB” → Mixer operations
• “What’s the current session tempo?” → Session information queries
• “Arm track 2 for recording” → Recording setup

✨ Features

Phase 1 (MVP) - In Development

• 🎮 Transport Control: Play, stop, record, navigation
• 📊 Session Information: Query tempo, sample rate, track count
• 🎚️ Track Management: Create, select, rename tracks
• 🎛️ Basic Mixer: Volume, pan, mute, solo controls
• 📝 Markers: Create and navigate to session markers

Planned Features

See ROADMAP.md for complete feature timeline:

• Advanced mixer operations (sends, inserts, automation)
• Plugin control and management
• Region editing and manipulation
• Snapshot and template management
• And much more!

🚀 Quick Start

Prerequisites

• Ardour 8.x with OSC enabled
• Python 3.10+
• uv package manager (recommended)

Installation

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh
 
# Clone the repository
git clone https://github.com/raibid-labs/ardour-mcp.git
cd ardour-mcp
 
# Install dependencies
uv sync --all-extras
 
# Run the MCP server
uv run ardour-mcp

Configure Ardour OSC

1. Open Ardour
2. Go to Edit → Preferences → Control Surfaces
3. Enable Open Sound Control (OSC)
4. Configure:
   • OSC Server Port: 3819 (default)
   • Feedback: Enable all feedback options
   • Click OK

Using with Claude Desktop

Add to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "ardour": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/ardour-mcp",
        "run",
        "ardour-mcp"
      ]
    }
  }
}

📖 Documentation

• Architecture Overview - System design and components
• Development Guide - Setup and contribution workflow
• OSC API Reference - Complete Ardour OSC command reference
• Roadmap - Feature timeline and milestones

🏗️ Architecture

Ardour MCP uses a three-layer architecture:

┌─────────────────┐
│   AI Assistant  │  (Claude, etc.)
└────────┬────────┘
         │ MCP Protocol
┌────────▼────────┐
│   MCP Server    │  (ardour_mcp)
│  ┌──────────┐   │
│  │  Tools   │   │  Transport, Tracks, Mixer, etc.
│  └────┬─────┘   │
│  ┌────▼─────┐   │
│  │  State   │   │  Cached Ardour state
│  └────┬─────┘   │
│  ┌────▼─────┐   │
│  │OSC Bridge│   │  Bidirectional OSC communication
│  └────┬─────┘   │
└───────┼─────────┘
        │ OSC Protocol (UDP)
┌───────▼─────────┐
│     Ardour      │  Digital Audio Workstation
└─────────────────┘

See ARCHITECTURE.md for detailed design.

🤝 Contributing

We welcome contributions from developers, musicians, and audio engineers!

• Check out CONTRIBUTING.md for guidelines
• Look for issues labeled good first issue
• Join discussions about features and design
• Help improve documentation
• Test and report bugs

📋 Current Status

Phase 1 (MVP) - Core Implementation 🚧

• ✅ Project structure and documentation
• ✅ OSC communication bridge (bidirectional, 84% coverage)
• ✅ State management with automatic updates
• ✅ Transport control tools (13 methods)
• ✅ Session information tools (9 methods)
• 🚧 Track management tools (next up)
• 📋 Testing expansion (in progress)
• 📋 MCP server integration (planned)

Test Results: 21/23 passing (91%) on OSC bridge

Target: February 2025

See ROADMAP.md for detailed timeline.

🎓 Resources

• Ardour Manual - Official Ardour documentation
• Ardour OSC Documentation - OSC protocol reference
• MCP Specification - Model Context Protocol documentation
• MCP Python SDK - Python implementation

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Ardour - Professional open-source DAW
• Anthropic - Model Context Protocol
• All contributors and testers

📧 Contact

• GitHub Issues: Bug reports and feature requests
• Discussions: Questions and community chat
• Maintainer: Raibid Labs

---

Built with ❤️ for the open-source audio and AI communities

First MCP server for professional audio production • Bridging creativity and AI assistance