Skip to main content
Glama
Ardour Ultra MCP
by Elias02345
README.md
# 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.

[![CI](https://github.com/Elias02345/ardour-ultra-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Elias02345/ardour-ultra-mcp/actions/workflows/ci.yml)
[![License: GPL v3+](https://img.shields.io/badge/license-GPL--3.0--or--later-blue)](LICENSE)
[![Python: 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](pyproject.toml)

[**Deutsch: Installation Schritt für Schritt**](docs/INSTALLATION.de.md) · [Installation](docs/INSTALLATION.md) · [MCP client setup](docs/MCP_CLIENTS.md) · [All documentation](docs/README.md)

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](docs/COMPATIBILITY.md) 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](docs/INSTALLATION.md#1-install-uv). 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.

```sh
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.**

```sh
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](docs/TROUBLESHOOTING.md#lua-file-io-is-blocked).

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

```sh
ardour-ultra-mcp test-connection
ardour-ultra-mcp doctor
```

Continue when `test-connection` reports **Connection OK** and `doctor` exits successfully. [Resolve a connection error](docs/TROUBLESHOOTING.md) before asking an agent to edit.

**5. Connect your MCP client.** Choose **one** [client setup](docs/MCP_CLIENTS.md): 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](docs/QUICK_START.md) continues with the first safe edit. [Full installation instructions](docs/INSTALLATION.md) cover updates, uninstalling and custom paths.

## 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.

| Area | Implemented scope |
|---|---|
| Session and mixer | Inspection, save/snapshot, tracks/buses/groups, gain/pan/mute/solo, transport and recording controls |
| MIDI | Internal region creation on 9.8, dense note batches, guarded edit/delete, copy and native undo |
| Plugins and routing | Generic inventory, parameters/presets, instruments, sends and backend ports |
| Regions and automation | Move/trim/split/copy/delete, gain/fades, bounded automation curves and modes |
| Render and analyze | Experimental preset-based master/range export; offline peak, RMS, LUFS, estimated true peak, spectrum, stereo and silence metrics |
| Safety and verification | Stable IDs, explicit units, preflight, destructive intent, structured changes/errors and scoped revision checks |

MIDI controller events, audio import/stretch/pitch shift, crossfades, stems, sidechain pins and complete session lifecycle control remain gaps. See the [generated tool reference](docs/TOOL_REFERENCE.md), [implementation status](docs/IMPLEMENTATION_STATUS.md) and [gap analysis](docs/FINAL_GAP_ANALYSIS.md).

## How it works

```mermaid
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](docs/SECURITY.md).

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](docs/DEVELOPMENT.md), [testing](docs/TESTING.md) and [contributing](CONTRIBUTING.md). 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](LICENSE). See [dependency and license notices](THIRD_PARTY_NOTICES.md), [research](docs/RESEARCH.md) and [architecture decisions](docs/ARCHITECTURE_DECISION.md).

TDQS

C2.7/5.0

Scored across 80 tools

Disambiguation4/5

Most tools target a distinct resource/action pair, and descriptions clearly delimit nearby operations such as track gain vs. send gain vs. region gain. The very large surface creates some risk of misselection among similar setter/getter families, but the naming and descriptions generally keep boundaries clear.

Naming Consistency4/5

The tool set overwhelmingly follows a verb_noun snake_case convention, with predictable list/get/create/delete/set families. Minor deviations like ping, doctor, play, stop, undo, and redo are conventional command names and do not seriously break consistency.

Tool Count2/5

Eighty tools is far beyond a practical, well-scoped MCP surface and will burden agent selection even though the DAW domain is broad. Many capabilities are legitimate, but the set is too large to be easily discoverable or safely composed without strong grouping.

Completeness4/5

Coverage is extensive across session, track, group, transport, region, MIDI, plugin, send, port, automation, undo, rendering, and analysis workflows. Some minor DAW lifecycle gaps remain, such as tempo-map inspection, marker management, and richer track routing operations, but core workflows are well represented.