Ardour Ultra MCP

Precise, local control of Ardour for MCP clients. Inspect a session, edit MIDI, adjust plugins, build automation and measure rendered audio through Ardour's real scripting APIs.

Deutsch: Installation Schritt für Schritt · Installation · MCP client setup · All documentation

The server is free, open source and local. It needs no API key, cloud service or proprietary model. Your choice of MCP client and model is separate. Control uses a reviewed Lua hook and optional native OSC; no mouse coordinates or image recognition.

Status: development release 0.1.0. Linux Ardour 9.8 has native integration evidence; 8.12 has a smaller tested feature set. The Python/MCP layer passes CI on Linux, macOS and Windows. Native macOS/Windows Ardour integration is unverified, with Windows heartbeat/file-replacement and permission hardening still open. Read compatibility before choosing a platform. The full production brief is not yet complete.

Get connected in five steps

Use a terminal on Linux/macOS, or PowerShell on Windows. You need Ardour installed and uv installed. You do not need Git or a separately installed Python for this route.

1. Install the server from GitHub. There is no PyPI release yet.

uv tool install --python 3.12 "ardour-ultra-mcp[analysis] @ https://github.com/Elias02345/ardour-ultra-mcp/archive/refs/heads/main.zip"
uv tool update-shell

Open a new terminal, then run ardour-ultra-mcp --version. The analysis extra includes local audio metrics.

2. Install the Ardour bridge.

ardour-ultra-mcp install

The command prints the script location and next steps. If it cannot detect Ardour, it selects major version 9 and says so. Use install --ardour-major 8 for an Ardour 8 installation.

3. Activate the hook in Ardour. Restart Ardour, open a disposable session, then choose Edit → Lua Scripts → Script Manager → Action Hooks → New Hook → Ardour Ultra MCP. These are Ardour 9.8 English labels; older versions/manuals may use Scripted Actions → Manage. The hook needs Lua file I/O, allowed by default in Ardour 9.8. If sandboxing was enabled, follow troubleshooting.

4. Check the connection. Keep Ardour and the session open.

ardour-ultra-mcp test-connection
ardour-ultra-mcp doctor

Continue when test-connection reports Connection OK and doctor exits successfully. Resolve a connection error before asking an agent to edit.

5. Connect your MCP client. Choose one client setup: Claude Desktop, Claude Code, Codex or generic STDIO. configure prints a ready-to-copy snippet with an absolute executable path. Your client launches the server; you normally do not run serve yourself.

Try this first:

Use Ardour Ultra MCP to inspect the connection, session and capabilities. List the tracks and report unsupported features. Make no changes.

The quick start continues with the first safe edit. Full installation instructions cover updates, uninstalling and custom paths.

Related MCP server: AI Sound MCP Server

What it can do

There are 80 typed MCP tools, 7 read-only resources and 1 workflow prompt. Runtime capability discovery reports what your Ardour build supports; registration alone does not guarantee availability.

MIDI controller events, audio import/stretch/pitch shift, crossfades, stems, sidechain pins and complete session lifecycle control remain gaps. See the generated tool reference, implementation status and gap analysis.

How it works

flowchart LR
  Client[MCP client / STDIO] --> Python[Typed Python control layer]
  Python --> Lua[Private mailbox / allowlisted Lua EditorHook]
  Lua --> Ardour[Ardour session and model APIs]
  Python --> OSC[Optional loopback OSC]
  Python --> Analysis[Local offline audio analysis]

The default server uses STDIO and opens no public listening service. Media/export paths are denied until explicitly permitted. There are no arbitrary Lua or shell execution tools. Undo grouping and compensated batches have different guarantees; revision checks do not observe every human edit. Read the security model.

You can explore without Ardour using ardour-ultra-mcp serve --backend fake. Results are labelled simulated; this backend cannot execute plugins or render audio.

Develop and contribute

Start with development, testing and contributing. CI checks Python 3.11–3.14 on Ubuntu, macOS and Windows. Native test evidence is reported separately from simulated tests.

Original implementation, licensed under GPL-3.0-or-later. See dependency and license notices, research and architecture decisions.