Dorico Maestro

An AI composition partner that remote-controls Steinberg Dorico through the Model Context Protocol (MCP).

Dorico Maestro turns Dorico into a shared canvas between a composer and an AI assistant. You discuss a musical idea in plain language; the assistant writes it into your open Dorico score, plays it back, and the two of you refine it together — bar by bar.

Status: early / experimental (v0.1). Connecting, reading live status and live note input are verified against Dorico 6. Most of the ~340 catalogued commands are not yet live-tested — each carries an honest status (verified / broken / untested); see docs/dorico_command_catalog.md.

---

How it works

You ⇄ Claude (LLM) ⇄ Dorico Maestro (MCP server) ⇄ Dorico (Remote Control · WebSocket 127.0.0.1:4560)
                                 │
                                 └─ music21 ⇄ MusicXML  (full-score generation & reading)

• Data-driven core — every Dorico command is described as data in commands.yaml; one generic builder/executor sends them, so behaviour is consistent and adding a command is a data change, not new code.
• Small, honest MCP surface — a handful of musical tools (add_notes, transpose, playback, …), a generic run_command, and a dorico://commands resource to discover the whole catalog. kOK from Dorico means accepted, not effective — results say which.
• Full-score awareness — Dorico's API can only read the current selection, so whole-piece understanding uses MusicXML + music21.

Requirements

• Steinberg Dorico (Remote Control API; introduced in Dorico 4, tested on Dorico 6), with Remote Control enabled.
• Python 3.11+.
• An MCP client (Claude Desktop / Claude Code).

Install

git clone git@github.com:romanstark/dorico-maestro.git
cd dorico-maestro
python -m venv .venv
.venv\Scripts\activate          # Windows  (use source .venv/bin/activate on macOS/Linux)
pip install -e ".[dev]"
pytest                          # optional: 87 tests, no Dorico needed

Enable Dorico's Remote Control

1. In Dorico, turn on the Remote Control API (it listens on 127.0.0.1:4560).
2. The first time Dorico Maestro connects, Dorico asks you to allow the connection — accept it. On the very first connect you may be prompted more than once (allow it twice); accept each time. A session token is then stored and reused, so later runs connect without a prompt.

Register with your MCP client

Add to your client's mcpServers config (adjust the path to your checkout):

{
  "mcpServers": {
    "dorico-maestro": {
      "command": "/absolute/path/to/dorico-maestro/.venv/Scripts/python.exe",
      "args": ["-m", "dorico_maestro.server"]
    }
  }
}

Restart the client, open a score in Dorico, then say "connect to Dorico".

Usage

Talk to the assistant naturally; it drives these tools:

• connect_to_dorico, get_status — connect and read Dorico's live state.
• add_notes(["C4","E4","G4"], duration="quarter") — enter notes at the caret (accidentals like "F#5"/"Bb3" supported), then leaves note input cleanly.
• add_rest, transpose, switch_mode, playback, save.
• run_command(command_id, params) — the escape hatch for any catalogued command.
• Resource dorico://commands (and dorico://commands/{category|status}) — discover the full command set and its verification status.

What works / current limits

• Verified live: connect + status, note input (pitch/duration/accidental), Edit.SelectAll/SelectNone/Copy, Window.SwitchMode, Play.Stop.
• Selection-only reads: there is no "read bar N" — the API reads only the current selection; whole-score reading will go via MusicXML export + music21.
• Popover-only actions not yet supported: time/key signatures and dynamics are entered via a Dorico popover whose value the API can't fill, so those tools report the limitation instead of silently doing nothing.
• kOK ≠ effect: tools verify where they can and say so; otherwise confirm in the score.

Contributing

Contributions are very welcome — via GitHub Issues and Pull Requests. CI runs the tests and linter on every PR. Because the project is dual-licensed (see below), contributors sign a lightweight CLA. Start with CONTRIBUTING.md.

Good first tasks: live-verify untested commands (flip their status in commands.yaml), enrich command params from Dorico's application.log, or help build the MusicXML round-trip.

License

AGPL-3.0-or-later — see LICENSE. The software is free and open; if you deploy a modified version, you must share your source under the same license.

Commercial licensing: if you want to use Dorico Maestro in a proprietary or closed-source product (AGPL terms don't fit), a separate commercial license is available — contact Roman Stark (mail@romanstark.de).

Documentation

• docs/architecture.md — how the data-driven design fits together
• docs/protocol.md — the reverse-engineered Dorico Remote Control protocol
• docs/dorico_command_catalog.md — all ~340 command IDs