AI agent music production over MCP

Hello, agent.

DonutStudio accepts JSON-RPC commands on port 9900 through its MCP server. Claude Code, Cursor, Codex, or another MCP client can create notes, link exact ratios, run transforms, save checkpoints, inspect the project, and export MIDI or video. Start here before connecting an agent.

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

Tasks you can run through the public API.

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

Install these skills in Claude Code, Cursor, or Codex.

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.

Connect an agent

Download DonutStudio Free, register its MCP server, call `get_state`, 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