Skip to main content
Glama
biogin

serum-gen-mcp

by biogin
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Serum 1 Preset Generator

Describe a sound in plain language — "aggressive cyberpunk bass that keeps the sub clean," or in Russian — to Claude Desktop, Claude Code, or another local AI chat app on your own computer. You get a real, ready-to-load Preset sitting in Xfer Serum 1's browser (User → AI).

It needs a local app, not claude.ai in a browser — it writes the Preset file straight into Serum's folder on your machine, which a web chat can't reach.

  • Free, no sign-up. Nothing to subscribe to, no API key to go get. If you can chat with Claude, you can use this.

  • Trustworthy. Every setting is checked against all 299 of Serum 1's real parameters before anything is written, so you don't get a broken preset.

  • Never loses work. It never overwrites an existing preset — a name that's taken gets _2, _3, and so on. Asking for a change always writes a new file; the one you started with is untouched.

  • Private. It never sends anything anywhere — it only reads and writes files on your own computer.

Results aren't guaranteed to be perfect — always load the preset in Serum and listen before you commit to it.

Install (Claude Desktop)

  1. Download the latest .mcpb file.

  2. Double-click it. Claude Desktop installs it and asks where your Serum presets live — leave that blank to use the standard location.

  3. Restart Claude Desktop.

Related MCP server: io.github.peterkolbe/ableton-for-ai

Try it

Ask Claude something like:

  • "deep sub bass for a dark trap beat"

  • "Make me a Serum preset: warm evolving pad, no reverb"

  • "bright plucky arp for a melodic house drop"

  • "warm pad, Don Toliver-ish", "glassy pluck, Four Tet style", "aggressive bass, Skrillex-ish" — style and artist references work too; Claude draws on its general sense of that sound (genre, mood, typical gear), not an exact reproduction of any one track

  • "тёмный мягкий пэд" — works in any language your chat app understands

  • "Make me a Serum preset: metallic FX riser", then "make the one you just made darker" — asking for a change always writes a new file; the original stays untouched

For developers

Other ways to install

Using Claude Code, or an MCP client other than Claude Desktop, pinned to a stable release, no clone needed:

claude mcp add serumv1-preset-generator -- \
  uvx --from git+https://github.com/biogin/serumv1-preset-generator@v1.0.0 serum-gen-mcp

Any MCP client that reads a JSON config (Claude Desktop's own claude_desktop_config.json, under Settings → Developer → Edit Config, works the same way):

{
  "mcpServers": {
    "serumv1-preset-generator": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/biogin/serumv1-preset-generator@v1.0.0",
               "serum-gen-mcp"]
    }
  }
}

Or hand the whole thing to an assistant with file/terminal access on the target machine:

Please set up the serumv1-preset-generator MCP server on this computer.

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

2. Register it as an MCP server pointed at
   https://github.com/biogin/serumv1-preset-generator (no need to clone it
   yourself -- `uv` fetches and builds it). If I'm on Claude Code, run:
   `claude mcp add serumv1-preset-generator -- uvx --from git+https://github.com/biogin/serumv1-preset-generator@v1.0.0 serum-gen-mcp`
   If I'm on Claude Desktop, add this to claude_desktop_config.json
   (Settings -> Developer -> Edit Config):
   {"mcpServers": {"serumv1-preset-generator": {"command": "uvx", "args":
   ["--from", "git+https://github.com/biogin/serumv1-preset-generator@v1.0.0",
   "serum-gen-mcp"]}}}

3. Tell me exactly what you did, then tell me to fully quit and restart my
   chat app (not just close the window) for it to take effect.

For development, or to configure beyond the defaults (SERUM_GEN_SERUM_ROOT, a custom Init template, etc. — see Configuration below):

git clone https://github.com/biogin/serumv1-preset-generator
cd serumv1-preset-generator
uv sync
claude mcp add serumv1-preset-generator --scope user -- \
  /opt/homebrew/bin/uv --directory "$(pwd)" run serum-gen-mcp

Use an absolute path for uv (Claude Desktop doesn't start servers with your shell's PATH) — replace /opt/homebrew/bin/uv with the output of which uv.

Architecture

No model call and no API key live anywhere in this codebase (ADR 0004): the calling MCP client designs the sound; this project only validates it against the Parameter Reference and writes the .fxp bytes.

Tools

Tool

Description

write_patch(patch, constraints=[])

Write a new preset from settings you designed. Returns a Patch Summary (the exact values written) and the Preset's path.

edit_patch(preset, changes, constraints=[])

Apply a partial change to an existing preset as a new Revision (<name>_v2, …); the original is never touched. Returns the Patch Summary plus every resulting difference.

list_parameters()

The full Parameter Reference: every settable name, its range/options and Init value, plus valid modulation sources/destinations and factory wavetables.

describe_preset(preset)

A human-readable summary of an existing preset's current settings and modulation matrix.

You don't call these by hand — the chat app builds them from your request, guided by this server's own instructions and list_parameters().

Command line

uv run serum-gen inspect path/to/preset.fxp   # every parameter and Routing of a preset

That's the only CLI command: designing or revising a preset from a description needs a model, and there's no model in this codebase — so there's nothing for a bare terminal command to call.

Configuration

All settings are optional, set in the environment or .env:

Variable

Default

SERUM_GEN_OUTPUT_DIR

Serum's Presets/User/AI

SERUM_GEN_SERUM_ROOT

/Library/Audio/Presets/Xfer Records/Serum Presets

SERUM_GEN_TEMPLATE

the packaged Init preset

Developed and tested on macOS; Windows and Linux likely work too via SERUM_GEN_SERUM_ROOT but are untested — there's no macOS-specific code anywhere in this project.

Known limitations

  • edit_patch has worked well on presets like "Biggest Hard 808" + "hit harder," but at least one case ("PR 808 Kick Circuit [SD]" + "hit harder") didn't clearly change the sound as asked, in testing before this project dropped its own model. Treat a Revision as a starting point to audition, not a guaranteed result.

  • Result quality tracks whatever chat app and model you're using — this server has no sound-design opinion of its own.

Development

uv run pytest        # no API key or network needed anywhere in this suite
uv run mypy          # strict
uv run ruff check && uv run ruff format --check

Tests that read the factory library skip when Serum isn't installed.

Prior art

serum-mcp does the same thing for Serum 2, whose .SerumPreset format Xfer doesn't publish (its own docs note parameters are shipped with confidence levels, not certainty). This project targets Serum 1's .fxp format instead, verified byte-for-byte against the installed factory library — a different synth version, not a better approach to the same one.

Design notes

CONTEXT.md (glossary) and docs/adr/ (decisions).

License

MIT

Available Tools

4 tools
describe_presetB

A human-readable summary of an existing preset's current settings and mod matrix.

    Args:
        preset: The preset's name as shown in Serum's browser (a partial name
            works if it's unique), or a full path to its .fxp file.
ParametersJSON Schema
NameRequiredDescriptionDefault
presetYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral burden. 'Summary' implies a read-only operation, but the description never explicitly states it makes no changes, requires no special permissions, or has any side effects or limitations. It also does not mention whether the preset must be loaded or active.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two compact sentences with the purpose front-loaded and an Args section for the parameter. There is no filler, though the indented multi-line Args formatting is slightly awkward for such a small definition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, return values need not be explained, and the single parameter is well covered. However, for a tool with three siblings, the definition omits how it relates to list_parameters and provides no explicit read-only assurance, leaving modest gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate fully for the single parameter, and it does: it explains that the value is a preset name as shown in Serum's browser, that a partial name works if unique, and that a full path to an .fxp file is also accepted. This is material information an agent would otherwise not have.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('human-readable summary') and resource ('an existing preset's current settings and mod matrix'), so an agent knows exactly what it reports. It implicitly distinguishes read-only inspection from the write-oriented siblings (write_patch, edit_patch), but does not explicitly differentiate it from list_parameters, which likely also inspects a preset's parameters.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit guidance on when to use this tool versus list_parameters, write_patch, or edit_patch, nor any stated preconditions. The only contextual detail is about the input format, which belongs to parameter semantics rather than usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

edit_patchA

Make a Revision of an existing Serum 1 preset: only the settings you list change.

    Writes a new Preset next to the others in User → AI (named <preset>_v2,
    _v3, ...; the original is never changed, and keeps its name) and returns
    a Patch Summary of what you set plus every resulting difference from the
    original.

    Args:
        preset: The preset's name as shown in Serum's browser (a partial name
            works if it's unique), or a full path to its .fxp file.
        changes: Only the settings to change; everything else keeps its current value.
        constraints: Hard requirements to check before writing.
ParametersJSON Schema
NameRequiredDescriptionDefault
presetYes
changesYes
constraintsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.8/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does well: it discloses the non-destructive write model, the naming scheme (_v2, _v3), that the original keeps its name and is untouched, and that a Patch Summary of changes plus all resulting differences is returned. It does not cover failure behavior when constraints are violated or any auth/permission requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core behavior and the non-destructive guarantee, then a compact Args block. Some sentences (the naming-parenthetical, the Patch Summary detail) are dense but each earns its place given the absence of schema descriptions.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return-value detail is largely covered, yet the description still usefully names the Patch Summary contents. For a 3-parameter mutation tool with no annotations, the main remaining gap is what happens when a constraint fails and whether the new preset is loaded or activated.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Top-level schema coverage is 0%, so the description's Args block is the main source of meaning for the three parameters: preset accepts a browser name (partial if unique) or a full .fxp path, changes should list only what to set, and constraints are pre-write hard requirements. This adds real value beyond the bare schema, though the constraint enum values themselves are left unexplained.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource ('Make a Revision of an existing Serum 1 preset') and clarifies scope ('only the settings you list change'). It implicitly distinguishes itself from write_patch by emphasizing that the original is never changed and a new _v2/_v3 preset is written, but it never names the sibling explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied rather than stated: use this when modifying an existing preset without destroying the original. The mention that constraints are 'Hard requirements to check before writing' gives some context, but there is no when-not guidance and no routing to write_patch or describe_preset for related needs.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_parametersA

The full Parameter Reference: every settable name, its range/options and Init

    value, plus valid modulation sources/destinations and factory wavetables.
    Call this whenever you're unsure of an exact name, range or option before
    write_patch/edit_patch.
ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden. It discloses that this is a read-style reference lookup and describes the categories of information returned, but says nothing about permissions, freshness/caching, or whether results are static. For a zero-parameter lookup tool this is strong but not fully complete.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with what the tool returns, followed by the actionable usage instruction. No filler, and the operative guidance ('call before write_patch/edit_patch') is placed where an agent will read it.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return-value documentation is not strictly required, yet the description still summarizes the payload categories, which is exactly what an agent needs to decide whether to consult it. Nothing required to invoke a no-arg reference tool is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes no input parameters, so per the rubric the baseline is 4 and there is nothing further to document. Schema coverage is 100% with an empty object, so no parameter semantics are missing.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names the resource precisely (parameter reference) and enumerates what it returns: settable names, ranges/options, Init values, modulation sources/destinations, and factory wavetables. It also explicitly distinguishes itself from the write_patch/edit_patch siblings, so an agent can identify it without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives an explicit trigger condition ('Call this whenever you're unsure of an exact name, range or option') and names the sibling tools it should precede (write_patch/edit_patch). This is textbook when-to-use guidance with the alternative workflow spelled out.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

write_patchB

Write a new Serum 1 preset from settings you designed.

    Returns a Patch Summary (the exact settings written) and the path of the
    Preset written into Serum's preset browser (User → AI).

    Args:
        patch: The settings to write.
        constraints: Hard requirements to check before writing (e.g. the producer
            said "keep the sub clean" or "no reverb").
ParametersJSON Schema
NameRequiredDescriptionDefault
patchYes
constraintsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It does usefully disclose side effects — a preset is written into Serum's browser at 'User → AI' and a Patch Summary plus path are returned, and constraints are validated before writing. However, it says nothing about overwrite behavior when a name already exists, permissions, or reversibility, which matter for a filesystem-writing tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core purpose is front-loaded in one sentence, followed by behavior and a compact Args block. The return-value sentence partially duplicates the existing output schema, which is minor waste, but overall the text is tight and easy to scan.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutating, file-writing tool with no annotations, the description covers the essential create-and-return flow and where output lands. Given a rich nested input schema and an output schema, the main remaining gaps are overwrite/collision behavior and how 'constraints' failures are surfaced.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Top-level schema description coverage is 0%, so the description must compensate. It adds meaning for both parameters: patch is 'the settings to write' and constraints are 'hard requirements to check before writing', with concrete examples that explain the otherwise bare enum. It still does not explain the patch sub-fields (name, params, routings, wavetables) at the top level.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a concrete verb and resource: 'Write a new Serum 1 preset from settings you designed.' The word 'new' implicitly separates it from the sibling edit_patch, though edit_patch is never named. An agent can identify what the tool does, but the sibling differentiation is left to inference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit guidance on when to use this versus edit_patch for existing presets, nor any stated prerequisites. The constraint examples ('keep the sub clean', 'no reverb') hint at production context but do not tell the agent when this tool is the right choice.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv0.2.0
    • First observeddescribe_preset
    • First observededit_patch
    • First observedlist_parameters
    • First observedwrite_patch
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4/5.0

Scored across 4 tools

Disambiguation5/5

Each tool targets a distinct operation: write_patch creates a new preset, edit_patch mutates an existing one, list_parameters is a reference lookup, and describe_preset reads a preset. The write vs edit boundary is clearly spelled out (new preset vs _v2 revision of the original), leaving no real ambiguity.

Naming Consistency5/5

All four tools follow a strict verb_noun snake_case pattern (write_patch, edit_patch, list_parameters, describe_preset) with no deviation in style or casing.

Tool Count5/5

Four tools is well-scoped for a focused Serum preset-generation task, and each one covers a necessary part of the authoring loop (create, revise, inspect, reference) without redundancy.

Completeness4/5

The surface covers the full create/read/update/reference lifecycle for preset authoring. Minor gaps exist: no delete_preset or list/browse operation for existing presets, though describe_preset's partial-name matching mitigates discovery.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers