@synthedit/mcp

A Model Context Protocol server that exposes SynthEdit's editor as native tools for AI agents — load/save .synthedit projects, list the module catalogue, add modules, connect cables, take screenshots, render audio.

It's a thin wrapper over SynthEditCL, the SynthEdit command-line tool.

Requirements

• Node ≥ 18
• A copy of SynthEdit installed (the server auto-detects it — see "How it finds SynthEditCL" below)

Install

npm install -g @synthedit/mcp

…or run on demand without installing:

npx -y @synthedit/mcp

Use it from Claude Code

Add this to your project's .mcp.json (or ~/.claude.json):

{
  "mcpServers": {
    "synthedit": {
      "command": "npx",
      "args": ["-y", "@synthedit/mcp"]
    }
  }
}

Restart Claude Code, approve the synthedit server when prompted (or run /mcp), and the se_* tools become available.

Tools

| Tool | What | |---|---| | se_load(path) | Open a .synthedit file. | | se_save_as(path) | Save the current document. | | se_rescan(include_vsts?) | Rebuild SynthEdit's plugin cache. Run this after building or installing a module — until you do, nothing else can see it. | | se_list_modules(path) | Dump the factory's module catalogue (IDs, categories, pin schemas) as XML. Read this once to discover module IDs and pin indices. | | se_dump(path) | Dump the loaded document recursively as JSON. | | se_screenshot(path, view?, scale?, transparent?, include_browser?, include_properties?, container?) | Render PNG of the loaded document. view: panel, structure (default), browser, or properties. | | se_render_audio(...) | Render audio output to a .wav file. | | se_script(commands) | Run several verbs in one round-trip. A batching convenience, not a requirement — see below. | | se_new, se_add_module, se_connect, se_select, se_deselect_all, se_delete, se_containerise, se_set_pin, se_set_param, se_rename | Edit verbs, operating on the session's current document. | | se_move(handle, x, y, view?) | Move a module. Two independent positions per module: structure (default) and panel (controls/containers only). | | se_export(format?) | Export the loaded project as a plugin (vst3 default, gmpi, juce). Reports the output paths. | | se_audio(action) | Start/stop/query the audio engine of an attached editor. | | GUI input: se_pointer, se_pointer_move, se_pointer_up, se_hover, se_drag, se_key, se_type, se_get_param | Drive mouse/keyboard into a project's panel headlessly. | | se_reset() | Discard the session and start clean on the next call. | | se_attach(pid?) / se_detach() | Point every tool at a running SynthEdit GUI instead of the headless session, so verbs act on the document the user has open. Windows and macOS. |

Results also carry a warnings array (single-result tools) or a second content block {"warnings":[…]} (se_script) whenever the engine printed something worth reading — duplicate modules, plugins that failed to load, dialogs suppressed by headless mode.

One persistent session

Tools share a single long-lived SynthEditCL process, so the document, handle aliases, selection and the live panel session all carry from one tool call to the next. se_new → se_add_module → se_screenshot works as three separate calls; so does se_load → se_drag → se_get_param.

The session ends on se_reset, on se_rescan (a rebuilt plugin cache can't be adopted by a running process), or on a crash — the last of which reports sessionLost in warnings, meaning the document is gone and needs reloading rather than the verb being retried. The next tool call respawns automatically.

See CLAUDE.md for the full agent-facing reference, including the handle-alias system used by se_script.

How it finds SynthEditCL

The server tries the following in order:

1. SE_CLI environment variable — full path to the executable. Use this when nothing else fits.
2. SE_BUILD_FOLDER environment variable — points at a CMake build directory. The server tries <build>/SynthEditCL/{Debug,Release,RelWithDebInfo}/....
3. Walk up from this file's location — if an ancestor directory has a sibling build/, try it. Lets repo contributors run the server straight out of a checkout.
4. <cwd>/build — covers MCP hosts that launch the server with the project root as the working directory.
5. Standard install locations — no source build required:
   • macOS: /Applications/SynthEdit.app/Contents/MacOS/SynthEditCL
   • Windows: %ProgramFiles%\SynthEdit\SynthEditCL.exe and %ProgramFiles%\SynthEditCL\SynthEditCL.exe (and (x86) variants)
   • Linux: /opt/SynthEditCL/SynthEditCL and ~/SynthEditCL/SynthEditCL — the usual places to extract the release tarball
6. SynthEditCL on PATH (SynthEditCL.exe on Windows) — checks each PATH directory, like which/where. Covers the Windows installer's "Add to PATH" option and a symlink into any bin directory.

So most users need zero environment configuration. Set SE_CLI or SE_BUILD_FOLDER only when your installation lives somewhere unusual:

{
  "mcpServers": {
    "synthedit": {
      "command": "npx",
      "args": ["-y", "@synthedit/mcp"],
      "env": { "SE_CLI": "/path/to/SynthEditCL" }
    }
  }
}

Versioning

The npm package is a thin wrapper around SynthEditCL. The actual engine — modules, DSP, the .synthedit file format — lives in the SynthEdit application itself, which you install via the regular SynthEdit installer.

The wrapper resolves the path to SynthEditCL at runtime on every tool call, so upgrading SynthEdit picks up new modules, bug fixes, and engine features automatically — no npm update needed, no Claude Code restart needed for engine changes.

Bump the wrapper only when something on the MCP side changes:

• A fix to the wrapper itself (path resolution, JSONL parsing, etc.)
• An MCP SDK upgrade you want to take advantage of
• A new ergonomic tool surface (the generic se_script already covers any new CLI verb)
• A schema change to an existing tool

Realistic cadence: a handful of wrapper releases per year, decoupled from SynthEdit's own release schedule.

License

MIT — see LICENSE.

The MIT license applies only to this wrapper package. SynthEdit itself (the engine and editor application) retains its own separate license terms; the wrapper does not relicense or otherwise affect them.