# superclean-mcp

MCP for Daniel M Karlsson's **SuperClean** SC pattern engine.

Layers on top of [`supercollider-mcp`](https://github.com/Ziforge/supercollider-mcp)'s OSC bridge — install setup.scd from that repo first, then use this MCP to control Pdefs, tempo, and hushing.

## Install

```bash
git clone https://github.com/Ziforge/superclean-mcp
cd superclean-mcp
pip install -e .
```

Same setup.scd install as supercollider-mcp — this MCP just uses the OSC bridge, no separate boot needed.

## Wire into Claude Code

```json
{
  "mcpServers": {
    "superclean": {
      "command": "superclean-mcp"
    }
  }
}
```

## Tools

| Category | Tool | What it does |
|---|---|---|
| Patterns | `play_pdef(name, pattern_code)` | Define + play a Pdef |
| Patterns | `stop_pdef(name)` | Stop by name |
| Patterns | `clear_pdef(name)` | Stop + remove from registry |
| Patterns | `hush()` | Stop all Pdefs (SuperClean muscle memory) |
| Patterns | `list_pdefs()` | Enumerate all Pdefs + isPlaying state |
| Patterns | `set_pdef_key(name, key, value)` | Live-inject a key/value into a running Pdef |
| Tempo | `set_tempo(bpm)` / `get_tempo()` | TempoClock.default |
| Setup | `superclean_setup(numChannels, orbits)` | Boot server + `~clean = SuperClean.new` |
| Setup | `load_synthdef_file(path)` | Load a .scd defining a SynthDef |

## Example prompts

- "Start a bass Pdef on cv3 that plays a random note from C minor every quarter"
- "What Pdefs are currently running?"
- "Push amp: 0.3 into the bass Pdef live"
- "Hush everything, then start just the pad pattern"
- "Set BPM to 137"

## Attribution

SuperClean is Daniel M Karlsson's SuperCollider quark. This MCP wraps its Pdef surface as MCP tools; the SuperClean project itself lives at https://github.com/dmkarlsson/SuperClean.

## Related MCPs

| Repo | For |
|---|---|
| [`supercollider-mcp`](https://github.com/Ziforge/supercollider-mcp) | Generic SC IDE bridge — this MCP depends on it |
| [`phase8-mcp`](https://github.com/Ziforge/phase8-mcp) | Korg Phase 8 |
| [`disting-nt-mcp`](https://github.com/Ziforge/disting-nt-mcp) | Expert Sleepers Disting NT |
| [`fh2-mcp`](https://github.com/Ziforge/fh2-mcp) | Expert Sleepers FH-2 |
| [`es9-mcp`](https://github.com/Ziforge/es9-mcp) | Expert Sleepers ES-9 |
| [`erae-mcp`](https://github.com/Ziforge/erae-mcp) | Embodme ERAE Touch II |
| [`elektron-mcp`](https://github.com/Ziforge/elektron-mcp) | Elektron devices |

## License

GPL v2. See [`LICENSE`](LICENSE).