serum-mcp

Generate, edit and save Xfer Serum 2 presets from a plain-English description — as an MCP server, so any MCP client (Claude Code, Claude Desktop, ...) can drive it directly.

You:    generate a dark, evolving pad with a slow chorus
Claude: [builds a PresetSpec from your description, calls
         generate_preset(spec)]
        Wrote ~/Documents/Xfer/Serum 2 Presets/Presets/User/PD - Dark Evolving Chorus.SerumPreset

        Osc A: ON  octave=-1  volume=0.75  table_pos=42.0
        Filter 1: ON  type=lowpass_24  cutoff=0.32  resonance=18%
        Env 1: attack=0.8s  decay=2.5s  sustain=0.70  release=3.0s
        FX chain: FXChorus (wet=45%)

Open Serum in whatever DAW you use (FL Studio, Ableton, Bitwig, ...), load the preset, done. serum-mcp never touches your DAW, never renders audio, and never loads the Serum plugin itself — it reads and writes the .SerumPreset file format directly.

Why

Existing "AI Serum preset" tools are either closed-source SaaS products or one-shot config-to-preset generators. serum-mcp is:

• Open source, MIT licensed.
• Native to your agentic coding workflow — it's an MCP server, not a separate web app. Ask for a sound the same way you'd ask for a code change.
• Conversational and iterative — edit_preset lets you refine an existing patch ("make it warmer", "add more resonance") instead of only generating from scratch.
• Transparent about its own limits — every parameter this tool knows about is documented with how confidently it was verified (see docs/PARAMETER_SCHEMA.md), because Xfer doesn't publish this format and we don't pretend otherwise.

See Prior art for how this compares to Serum-Preset-Generator, SerumPresetGenerator, and Pounding Systems' AI preset generator.

Scope — what this is not

By design, and deliberately not planned for later:

• No MIDI generation or writing.
• No real-time DAW control, automation, or plugin scripting (no FL Studio MIDI scripting, no Ableton Remote Script, no ReaScript).
• No loading of the Serum plugin itself — this tool does not render or preview audio. Input is text, output is a .SerumPreset file.
• No DAW dependency anywhere in the pipeline. FL Studio is only where the author happens to open Serum afterwards; any DAW works identically.

A V2 direction — "reproduce this sound from an audio file" — is kept in mind architecturally but not started.

Install

Requires Python 3.11+ and uv. No API key of any kind is required — see How it works for why.

Not comfortable with the command line? Let an LLM do it for you

Most people reaching for this tool are producers, not developers. If the steps below look intimidating, paste this into Claude Desktop (or any LLM assistant that has file/terminal access on your computer) instead of typing any of it yourself:

Please set up the serum-mcp MCP server on this computer so I can use it
with my MCP client.

1. Install `uv` (a Python package manager) if not already installed --
   on Windows: run
   `powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"`
   on Mac/Linux: run `curl -LsSf https://astral.sh/uv/install.sh | sh`

2. Clone https://github.com/Celian-mrc/serum-mcp somewhere on this
   machine (or download it as a ZIP and extract it), then run `uv sync`
   inside that folder.

3. Find my Serum presets folder -- in Serum, the hamburger menu ->
   "Show Serum Presets folder" -> note the path ending in Presets/User
   (Presets\User on Windows).

4. Add serum-mcp as an MCP server in my client's config, pointing
   `--directory` at the folder from step 2 and setting
   SERUM_PRESETS_PATH to the path from step 3. If I'm on Claude Desktop
   for Windows, the config file is claude_desktop_config.json -- NOTE:
   if Claude Desktop was installed via the Microsoft Store, the real
   config file is NOT in the normal %APPDATA%\Claude location, it's
   under %LOCALAPPDATA%\Packages\Claude_<random id>\LocalCache\Roaming\Claude\
   -- search for claude_desktop_config.json across %LOCALAPPDATA% if the
   normal path doesn't have it or seems unused. If I'm on Claude Code,
   use `claude mcp add serum-mcp -- uv --directory <path> run serum-mcp`
   instead.

5. Tell me exactly what you did, then tell me to fully quit and restart
   my MCP client (not just close the window) for the change to take
   effect.

If you don't have filesystem/terminal access to do any of this, say so
clearly and walk me through the manual steps from serum-mcp's own README
instead.

Otherwise, do it yourself:

git clone https://github.com/Celian-mrc/serum-mcp
cd serum-mcp
uv sync

Configure your Serum presets folder

Serum's user preset folder location varies by install — find yours via Serum's hamburger menu → "Show Serum Presets folder" → the Presets/User subfolder. Then set:

export SERUM_PRESETS_PATH="/path/to/Serum 2 Presets/Presets/User"

If unset, serum-mcp falls back to a couple of known default install locations (see src/serum_mcp/config.py) before failing with a clear error — it never silently guesses or hardcodes a path.

If you ask for a custom-synthesized wavetable (custom_harmonics) or a wavetable sliced from one of your own audio files (sample_source, e.g. "turn this drum one-shot into a wavetable" — see How it works), serum-mcp also needs Serum's Tables folder (a sibling of Presets/) to write the generated .wav into. It's derived automatically from SERUM_PRESETS_PATH; override with SERUM_TABLES_PATH if your install doesn't follow the standard layout. Note sample_source slices the file into a wavetable, it does not play the sample back faithfully.

If you instead ask to keep a one-shot/sample recognizable (sample_playback_source, e.g. "turn this drum hit into a preset" or "layer this vocal chop with a synth pad"), serum-mcp uses Serum's actual sample-playback engine (SampleOsc) and copies the file into Serum's Samples folder (also a sibling of Presets/, derived automatically or overridden via SERUM_SAMPLES_PATH). Only .wav is supported for this (confirmed working live, despite every factory preset referencing .flac instead — see docs/PARAMETER_SCHEMA.md §8). The sample plays back at its originally recorded pitch/speed when C5 is played — a fixed reference note, not configurable. If the source file is stereo, its channels are gain-balanced by default (sample_center_pan) to correct any left/right level bias in the original recording (common — real one-shots are often mic'd slightly off-center) without altering either channel's actual content.

Any of these (custom_harmonics, sample_source, sample_playback_source, granular_source, spectral_source) write a file outside the .SerumPreset itself — the same real Serum limitation as a wavetable hand-drawn in Serum's own editor, not something this tool routes around. generate_preset/ edit_preset surface this: if the write depends on one of these files, the returned path is followed by a note listing it, so you know to send that file along too if you share the preset with someone else.

Optionally, set SAMPLE_BANK_PATH to the root of your own one-shot/drumkit library (unrelated to Serum's own folders — this can point anywhere). With it set, list_sample_files() can be called with no arguments and defaults to browsing that folder, which lets the calling model proactively check whether you have a fitting one-shot for a request even if you didn't explicitly mention your sample bank. Not set by default, and nothing reads your filesystem unless you configure this or point the model at a directory yourself.

Add to Claude Code

claude mcp add serum-mcp -- uv --directory /path/to/serum-mcp run serum-mcp

Or add manually to .claude/settings.json / ~/.claude.json:

{
  "mcpServers": {
    "serum-mcp": {
      "command": "uv",
      "args": ["--directory", "/path/to/serum-mcp", "run", "serum-mcp"],
      "env": {
        "SERUM_PRESETS_PATH": "/path/to/Serum 2 Presets/Presets/User"
      }
    }
  }
}

Add to Claude Desktop

Same shape, in Claude Desktop's claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "serum-mcp": {
      "command": "uv",
      "args": ["--directory", "/path/to/serum-mcp", "run", "serum-mcp"],
      "env": {
        "SERUM_PRESETS_PATH": "/path/to/Serum 2 Presets/Presets/User"
      }
    }
  }
}

Tools

| Tool | Description | |---|---| | generate_preset(spec, subfolder=None) | Build a new preset from a PresetSpec and write it to your Serum presets folder. subfolder (e.g. "RAGE Bank") nests a themed set of presets together instead of writing them flat. | | edit_preset(preset_path, spec) | Apply a partial PresetSpec update to an existing preset. Renames the file if spec.name changes (Serum's browser displays the filename, not internal metadata). | | list_parameters() | Full documented parameter schema (names, ranges, units, enum values, confidence) as JSON. | | describe_preset(preset_path) | Human-readable summary of a preset's current sound-shaping parameters. | | find_reference_presets(query, limit=8) | Search Serum's Factory library plus your own installed banks by folder/filename keyword match — for grounding a genre/artist-style request ("dubstep bass", "in the style of Flume") in a real, already-designed preset instead of generating purely from parametric knowledge. Genre queries are expanded against a small curated keyword table bridging genre names to Serum's role-organized Factory folders. | | list_sample_files(directory=None) | List audio files under a folder (e.g. a drumkit/sample bank) as JSON — path, name, size, and duration/sample rate/channels for .wav — so a specific file can be picked by name/folder context instead of guessed. Defaults to SAMPLE_BANK_PATH if directory is omitted. | | analyze_sample_file(path) | Lightweight acoustic descriptors for one .wav one-shot as JSON — brightness, tonal/noisy texture, a gated pitch estimate, attack/sustain shape — for when filenames within a sample-bank category aren't descriptive enough on their own. Also surfaces embedded_metadata (root note, sample-accurate loop points) when the sample pack's creator embedded RIFF inst/smpl tags — not universal, empty when absent. |

You don't write PresetSpec JSON by hand — the calling model (Claude Code, Claude Desktop, ...) builds it from your natural-language request using the tool descriptions and list_parameters() as a guide, the same way it would construct arguments for any other MCP tool.

How it works

Prompt (natural language)
        │
        ▼
The calling model (Claude Code / Claude Desktop) translates the request
into a PresetSpec (generation/spec.py) itself -- no separate LLM call.
This server has no model of its own to call.
        │
        ▼
generate_preset(spec) / edit_preset(path, spec)   (MCP tool)
        │
        ▼
preset/mapping.py  ── merges the validated PresetSpec onto a base preset
        │              (fixtures/init_preset.SerumPreset for generation, the
        │              existing file's own state for edits), validating
        │              every value against preset/schema.py's ground-truth
        │