AI agent music production over MCP — DonutStudio

Hello, agent.

DonutStudio is agent-controllable by design. Its full editing surface is exposed through a JSON-RPC command server on port 9900, fronted by a Model Context Protocol (MCP) server. Any MCP-compatible client (Claude Code, Cursor, Codex, or your own host) can drive DonutStudio: lay down notes, link them with exact ratios, run transforms, save checkpoints, export MIDI and video, and read back the result. This page is the canonical entry point: what you can do, how to start, and the rules of engagement.

How to start

Three steps from zero to a working agent loop.

1. Register the MCP server

In your MCP client config, point a server entry at the local DonutStudio MCP server (the JSON-RPC surface on http://localhost:9900). The MCP server exposes a tool per `arbit` method.

2. Confirm you can read state

Call `get_state` and `get_notes` first. Confirm the project's note count, track list, and tuning state match what you expect before mutating.

3. Save a checkpoint before any destructive op

`save_checkpoint` writes the entire project to disk in one undo step. Call it before batch_transform, clear_notes, or any operation that might be hard to reverse.

What you can do

Grouped by intent. Every entry maps to a public API method.

Compose

create_notes (batched), create_link (with a slaveHarmonic/masterHarmonic ratio), get_notes, get_links, get_note_frequency, set_cents_offset, batch_transform (quantize, humanize, retrograde, legato, staccato, transpose, scale_velocity, root_path_tune, and more).

Audition

preview_note (plays with the correct tuning), set_playhead, play, stop, set_bpm. Use get_audio_meters and reset_audio_meters to confirm you're hearing sound and not silence or clipping.

Shape the sound

set_track_instrument (soundfont / dx7 / diffsinger / va / external MIDI), set_track_volume / pan / adsr / reverb, get_soundfonts, get_presets.

Save and export

save_checkpoint, export_midi, export_arbit, export_audio (offline render, standalone only), export_dawproject.

Inspect

get_state, get_notes, get_links, get_tracks, get_tuning_state, get_transport, get_spectrum, get_loudness, get_debug_log.

Example agent tasks

Concrete things an agent can do end-to-end.

Build a JI-tuned chord progression

Pick a root, apply chord templates via the chord-aware tooling, link each chord tone with the correct ratio, save a checkpoint, and export to .mid and .arbit.

Auto-link from a chord

Lay down a chord with create_notes, then call the auto-link transform to derive every slave note's ratio from the chord root in one undo step.

Quantize + humanize

Run a 16th-note quantize, then a humanize pass with a small timing variance. Save a checkpoint between the two so you can revert the humanize if it lands wrong.

Detect beats and snap-arrange

For an imported audio clip, run beat detection and re-cut the arranger timeline to the detected grid.

Render a score-reactive video (Pro)

Build a Media Machine preset that reads notes, microtonal tuning, and harmonic content; render and export to MP4.

Agent skills

Drop-in skills for the major coding agents.

Skills README

Start here. Lists every skill, what it teaches the agent, and how to install it for Claude Code, Cursor, or Codex. — https://github.com/DonutsDelivery/donutstudio/blob/main/skills/README.md

DonutStudio Video Editing skill

Walk-the-video-editor skill: timeline, effects, transitions, text, export. — https://github.com/DonutsDelivery/donutstudio/tree/main/skills/donutstudio-video-editing

Do

Patterns that work.

Read before you write

Call get_state / get_notes / get_links before any mutation. Confirm the actual project state before changing it.

Checkpoint before destructive ops

save_checkpoint before clear_notes, before large batch_transforms, and before exporting over an existing file.

Prefer batched entry points

create_notes is one undo step for the whole batch; the per-note create_note is one undo step per call. Use the batched form.

Use the tuning-aware tools

preview_note plays with the correct tuning; get_note_frequency returns the actual frequency following the harmonic chain. Prefer them over fixed-pitch MIDI previews.

Pin the version

Read softwareVersion from the /donutstudio page's structured data. Don't assume a minimum version — read it at runtime.

Do NOT

Out of scope. Out of bounds.

Don't look for the source

DonutStudio is closed-source proprietary software. There is no public source tree. The github.com/DonutsDelivery/donutstudio repo holds only documentation, example scripts, and installer release artifacts.

Don't link to private paths

Don't expose, link to, or imply any private file path, internal endpoint, license-server URL, or build artifact that isn't on donutsdelivery.online or github.com/DonutsDelivery/donutstudio.

Don't bypass the public API

Drive the app through the MCP server (port 9900) or the `arbit` Lua API. Don't reach for undocumented internal protocols or memory-layout tricks.

Don't treat the repo as the source

The repository has `docs/`, `examples/`, `skills/`, and `flatpak/`. It does NOT have the application, build system, license server, or DSP engines.

Take it for a spin

Download DonutStudio Free, register the MCP server in your client of choice, and start composing.

Download DonutStudioAPI & scriptingFeatures

Related pages

Inline links to every page an AI agent or non-JS client might need. The page top nav (Features … Download) is JS-rendered from data/projects.json:donutstudio.subnav.

  • Features: /donutstudio/features — every major feature in one place.
  • API & scripting: /donutstudio/api — the public arbit scripting surface, MCP server reference, and links to docs/, examples/, skills/.
  • For AI agents: /donutstudio/agents — how to start, what you can do, example tasks, do/don't.
  • About: /donutstudio/about — one-person project in Denmark.
  • Download: /donutstudio/download — installers for Windows, macOS, Linux.
  • DonutStudio overview: /donutstudio — the home page.
  • MCP server port: localhost:9900 (JSON-RPC; the same surface the arbit Lua API exposes).
  • Public docs on GitHub: https://github.com/DonutsDelivery/donutstudio/tree/main/docs
  • Agent skills on GitHub: https://github.com/DonutsDelivery/donutstudio/tree/main/skills