studio-one-mcp

An MCP server for PreSonus Studio One. It lets Claude and other MCP clients read your songs and control a running Studio One.

Studio One has no public API, no OSC, and no network scripting. This server combines two things it does have:

Status: early. Developed against Studio One 5.5.2 on macOS. Paths for Windows and for Studio One 6/7 and Studio Pro 8 are wired in but untested.

An independent project, not affiliated with or endorsed by PreSonus or Fender. Studio One is their trademark.

Tools

Install

You need Node.js 20 or newer and Studio One.

npx -y studio-one-mcp setup

That is the whole install: npm fetches the package and the guided setup below takes it from there. To work on the code instead, clone it and run setup from the checkout, which then registers that checkout:

git clone https://github.com/NeanderthalMan/studio-one-mcp.git
cd studio-one-mcp
npm install
npx studio-one-mcp setup

setup walks you through each step and asks before changing anything:

1. It finds your Studio One user profile.
2. It installs the MCP Bridge device into it, and a small extension (Extensions/studio-one-mcp.edittasks) that lets the bridge edit notes.
3. It checks for a virtual MIDI port, which acts as the bridge's doorbell:
   • macOS: the built-in IAC Driver. setup can open Audio MIDI Setup for you. Tick Device is online under IAC Driver.
   • Windows: install loopMIDI and add a port named studio-one-mcp.
4. It registers the server with Claude Code (all projects) and, if you want, Claude Desktop. Installed with npx, it registers npx -y studio-one-mcp@<this version>, pinned so the server always matches the device it installed; from a clone, it registers that checkout. It backs up the Desktop config before editing it. For any other client, it prints the JSON to paste.
5. It shows the one step you do in Studio One: Preferences… (⌘,) on a Mac, Options on Windows → External Devices → Add… → studio-one-mcp → MCP Bridge. Set Receive From to your virtual MIDI port, and Send To to None. Restart Studio One first if it was running.
6. It waits for Studio One to answer.

From a clone, npm run setup does the same thing. Use --yes to accept the defaults, --dry-run to see what it would do, and --profile <dir> to pick a profile.

If something doesn't work, run:

npx -y studio-one-mcp doctor   # from a clone also: npm run doctor

It checks every link in the chain and tells you how to fix the first broken one: Node, profile, Songs folder, device installed and current, edit-task extension installed and current, MIDI port, Studio One running, bridge loaded, bridge answering, the edit task loaded in Studio One, and MCP client registration. setup treats the device and the extension as one install: if either is missing or out of date (for example after an update), it offers to reinstall both.

To remove the device and the extension: npx -y studio-one-mcp uninstall, then remove MCP Bridge under External Devices.

To update: npx -y studio-one-mcp@latest setup. It reinstalls the device and the extension and registers the new version. From a clone: git pull, then setup again. Either way, restart Studio One afterwards: it loads the device and the extension only at startup.

Without the live bridge: the song_* tools need nothing but the MCP registration. They read your .song files directly.

Configuration

How the live bridge works

Studio One runs control-surface scripts in an embedded SpiderMonkey engine. Scripts can read and write files but cannot open sockets, so the bridge is a folder. Studio One 5 also gives scripts no usable timer, so the bridge is event-driven. After writing a request, the server presses MIDI note 119 on a virtual MIDI bus (the macOS IAC Driver). The device's surface file maps that note, as a trigger control, to a toggle on a component parameter, and the component answers on each change.

flowchart LR
  client["MCP client<br/>(Claude)"] <-->|stdio| server["studio-one-mcp<br/>server (Node)"]
  server -->|"1 write request.json"| mailbox[("mailbox folder<br/>request.json<br/>response.json<br/>status.json")]
  server -->|"2 press note 119"| iac["virtual MIDI bus<br/>(IAC Driver)"]
  subgraph s1 ["Studio One"]
    device["MCP Bridge device<br/>(control-surface script)"]
    doc["song, mixer, transport,<br/>commands"]
    task["MCP Edit task<br/>(extension)"]
  end
  iac -->|"3 note wakes the script"| device
  mailbox -->|"4 read request"| device
  device <-->|"5 run the op"| doc
  device -.->|"note edits only"| task
  device -->|"6 write response.json"| mailbox
  mailbox -->|"7 read response"| server

status.json    device → client   session id and heartbeat; refreshed whenever the bridge runs
request.json   client → device   {id, op, args}, written atomically (tmp + rename)
response.json  device → client   {id, ok, result | error}

One request, step by step:

sequenceDiagram
  autonumber
  participant C as MCP client
  participant S as studio-one-mcp server
  participant M as mailbox folder
  participant B as IAC Driver (MIDI)
  participant D as MCP Bridge device in Studio One
  C->>S: tool call, e.g. live_set_channel
  S->>M: read status.json (is the bridge loaded?)
  S->>M: write request.json {id, op, args} (tmp file, then rename)
  loop every 150 ms until answered (5 s timeout)
    S->>B: note 119 (the doorbell)
    B->>D: trigger toggles the bridgeTick parameter
  end
  D->>M: refresh status.json (heartbeat)
  D->>M: read request.json
  Note over D: a new id? run the op in Studio One. An id already answered is skipped, so repeat presses are harmless.
  D->>M: write response.json {id, ok, result | error}
  loop every 20 ms
    S->>M: read response.json
  end
  Note over S: the response id matches the request id
  S->>C: result, or the error as a tool error

The client re-sends the press every 150 ms until a response arrives. The component answers each request id once, and the client sends one request at a time (the mailbox has a single slot).

For note edits (live_edit_notes) there is one more hop inside Studio One, described under Editing notes: the device writes the operations to edit-request.json, runs the MCP Edit command, and reads edit-result.json before it writes its response.

Two rules for anything that runs inside Studio One, both learned on 5.5.2:

• Never throw. An exception raised while Studio One is calling into a script becomes a modal Scripting Error dialog, even when the code catches it. While that dialog is open, some edits (mute, solo) silently do not apply. The device scripts return errors as values, and a test enforces it.
• Never call a member of a host object without first checking that it exists. A TypeError on a host object raises the same dialog.
• The same goes for code sent through live_eval. A throw there popped the dialog in testing, the first time in a session, even though the bridge catches it and reports the error.

Editing notes

A control-surface script can read notes but not change them. Studio One's own Musical Functions (Transpose, Velocity, Quantize…) are edit tasks: scripts that Studio One hands the selected notes and a set of editing functions. studio-one-mcp installs one of its own, MCP Edit, as a user extension: a folder in the profile's Extensions with a ZIP .package inside (a loose Scripts folder is not scanned). It shows up as the command Musical Functions/MCP Edit. For live_edit_notes, the bridge writes the operations to mailbox/edit-request.json, selects the track's parts, runs that command, and reads mailbox/edit-result.json. The task asks for no dialog, so none opens, and it applies only a fixed set of operations, never code from the mailbox.

The extension carries a second task, MCP Track Edit (Track/MCP Track Edit), for what a control-surface script cannot change on tracks: routing a channel's output (through the same connectChannel that Studio One's "Add Bus for Selected Channels" uses), moving tracks into folders, and renaming events. It works the same way, through track-edit-request.json and track-edit-result.json, and needs no selection. Its song-structure operations are in McpTrackOps.js: track order, instrument tracks, plug-ins and FX sends, single events, arranger sections, markers and time signatures. Everything one run of the task changes is one undo step. Studio One reads the package each time the task runs, so a reinstall takes effect without a restart (the bridge device itself still needs one).

What these found out about Studio One 5.5.2, in short:

• The Marker Track and Arranger Track are the first two tracks the song's own track iterator gives, and their events are the markers and sections, with names. Event times are numbers in each event's own time format (seconds, samples or quarter-note beats), converted through a MediaTime.
• A track leaves a folder for the top level right after that folder, and a top-level track does not move at all, so reordering goes through a temporary folder made at the target place.
• DeviceEditFunctions.insertDevice (what Studio One's own Insert FX task uses) puts plug-ins on the undo stack; the insert folder's own insertDeviceClass does not. Into a channel's Sends it makes an FX channel with a send. A send to an existing bus has no scripted route.
• Commands that open a dialog take its values as arguments (findCommand(...).arguments lists them, e.g. Bar, Numerator, Denominator for Insert Time Signature). Given as numbers they run without the dialog; given as strings the dialog opens and blocks the bridge until someone closes it.
• Edit/Paste goes to the editor's focus track, not the selected one; the task focuses the target first.
• There is no scripted way to add automation envelope points, so live_write_automation records them the way a person would, in Write mode.
• With an arranger section selected, Edit/Copy takes the section and everything under it, and Edit/Paste inserts that at the playhead; Edit/Delete and Cut take only the section. Edit/Delete Time in Loop removes a range from every track, section and marker.

Watching for changes

live_changes takes a snapshot of the song on every call (tracks and their events, the mixer, plug-ins, tempo, loop, markers and sections), keeps it in the studio-one-mcp data folder per song, and reports the difference from the previous one. The first call for a song only takes a look. Changes are net (a fader moved and moved back is no change) and do not say who made them.

Studio One 5.5.2 can also notify scripts of changes (Host.Signals.advise), and a live feed built on that was tried and dropped: it crashed Studio One three times. Reading a parameter's text while a song was closing crashed it at once; unsubscribing from an object that was already gone crashed it about a minute later; and unsubscribing while Studio One quit crashed it at quit. A close does send the DocumentManager's activeDocumentChanged before tearing the song down, but there is no such notice before quitting, so there is no safe moment to let go. Comparing snapshots touches none of that.

Undo

Changing a mixer parameter and setting it back (volume, monitor, a plug-in parameter, automation mode) is recorded as one undo step that changes nothing, and it is recorded late, on top of edits made after it. So an Undo right after such a change can remove that invisible step instead of the edit you just made. Check the song after undoing, and undo again until your edit is gone. The live tests do exactly that, and they stop and redo if an undo changes the song's track or channel count unexpectedly.

Testing

npm test            # unit and end-to-end tests; no Studio One needed
npm run test:live   # against a running Studio One with the bridge installed

The unit tests run the real device scripts and the edit task under node:vm against a fake Studio One host (test/helpers/s1host.js). The live tests change only what they restore, and check the song afterwards (tracks, channels and the track selection are compared at the end of the run). They never record, save or bounce.

• Set and set back: one channel's mute, solo, volume, monitor and automation mode; a plug-in parameter (directly and through a snapshot); a send level; the metronome's click and precount length; the tempo, playhead and loop; takes (next/previous and go-to).
• Edits that are then undone: a split, an added track, an added and duplicated take, a bus, and note edits (a transpose, a velocity and a quantize) through the edit task; a track moved, a plug-in added, an instrument track added, an event moved with gain and a fade, an event copied, a section added and renamed, a named marker added and renamed. Undo runs until the edit is gone (see Undo).
• A time signature inserted at bar 9 and removed again.
• Not in the live suite: live_add_send (not reliably undone) and live_write_automation (it plays the song). Both were checked by hand on a scratch song, the automation by saving and reading the envelope back.
• A marker is added at 3.25 s and deleted; a track's events are muted and unmuted; a track is muted and muted again (track mute is not on the undo stack); a scratch track is added, renamed, recoloured and removed.
• Some tests need something in the song and skip without it: a PreSonus plug-in on a channel, a send, a track with takes, an instrument track with notes, and two saved arranger sections.

File/Save is only checked, never run. Record modes and bouncing are not in the live suite: record modes cannot be read back to restore them, and every bounce leaves a file in the song folder.

Security: anything that can write to the mailbox folder, which means anything running as your user, can drive Studio One through it. With --allow-eval, it can also run arbitrary script inside Studio One. Keep the folder local, and leave eval off unless you are exploring.

Format notes (.song)

These were verified on songs saved by Studio One 5.5.2:

• Events and markers with timeFormat="2" are in quarter-note beats. An audio event's length equals the clip's frameCount / sampleRate × bpm / 60.
• TempoMapSegment@tempo is seconds per quarter note, so 0.5 means 120 bpm.
• The transport's position and loop points are in seconds.
• Mixer gain is linear amplitude, and pan runs from 0 to 1 with 0.5 as centre.
• A track's takes are Layers, and MediaTrack@activeLayer picks the one that plays.
• Tracks link to mixer channels through UID x:id="channelID", which matches the channel's uniqueID.
• Insert slots are the unnamed <Attributes name="FXnn"> children of Inserts. Siblings with an x:id (Presets, Combinator) are rack state.

Prior art

• tiwadara/StudioOneMcp drives Studio One through MIDI, Mackie Control and UI automation. It is write-only.
• Alari81/studio-control proved the file-mailbox device pattern on Studio Pro 8. It uses a different, noncommercial license, and no code from it is included here.
• CSources/Studio-Pro-Scripting-API-Reference is a community reference for the scripting API.

Studio One is a trademark of PreSonus Audio Electronics / Fender. This project is not affiliated with either.

License

MIT