@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_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?) | Render PNG of the loaded document. view: panel or structure. | | se_render_audio(...) | Render audio output to a .wav file. | | se_script(commands) | Run a multi-verb script in a single CLI process — preferred for editing flows because the document state persists across verbs. | | se_new, se_add_module, se_connect, se_select, se_deselect_all, se_delete, se_containerise, se_set_pin | Atomic edit verbs. Each spawns a fresh CLI process and exits — most editing flows want se_script instead. |

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 (x86))

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.