# supercollider-mcp

MCP bridge to a running SuperCollider IDE. Lets an MCP client (Claude Code, Cursor, Continue, etc.) evaluate SC code, query values, capture the post window, and screenshot Qt windows without the user having to paste anything.

Sits alongside the other Ziforge MCPs for the EMS Stockholm rig — see [Related MCPs](#related-mcps).

## How it works

sclang has a built-in OSC listener on port 57120. The setup.scd this repo ships with installs an `OSCdef` on `/mcpEval` that runs whatever code the MCP sends. Results come back on `/mcpReply` on port 57121, keyed by a request id.

Once you evaluate `setup.scd` in your IDE once per SC session, every MCP-side `sc_eval` call goes through OSC — no need to keep pasting.

```
Claude ↔ MCP server ↔ OSC :57120 → sclang → OSC :57121 → MCP → Claude
```

## Install

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

Or with uv:

```bash
uv pip install -e .
```

## Wire into Claude Code

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

## Setup — one line per SC session

Open your SC IDE, evaluate this once:

```supercollider
"~/Projects/supercollider-mcp/setup.scd".standardizePath.load;
```

You should see in the post window:

```
supercollider-mcp: listener installed on /mcpEval + /mcpPost (port 57120).
supercollider-mcp: replies sent to /mcpReply on 57121.
```

That's it. Now MCP calls work.

## Tools

| Category | Tool | What it does |
|---|---|---|
| Eval | `sc_eval(code, timeout)` | Send SC code, get result string |
| Eval | `sc_query(expression, timeout)` | Same as sc_eval but semantic — for reading state |
| Eval | `sc_post_recent(n)` | Last N eval results + errors from the OSC buffer |
| Patterns | `sc_hush()` | `Pdef.all.do(_.stop)` |
| Server | `sc_boot_server()` | Boot Server.default |
| Server | `sc_quit_server()` | Quit Server.default |
| Interp | `sc_recompile()` | Recompile class library (destroys the OSC listener — re-run setup.scd after) |
| Windows | `sc_list_windows()` | Enumerate sclang / SuperCollider windows via osascript (macOS) |
| Windows | `sc_screenshot(save_path)` | screencapture full screen (macOS) — the sclang Qt windows appear on it |
| Setup | `sc_setup_listener_scd_path()` | Return absolute path to setup.scd for the current install |

## Limitations

- **`sc_recompile` kills the listener.** After a class-library recompile, the OSC listener is gone. You must re-evaluate setup.scd. There's no way around this — recompile reboots the interpreter.
- **Post window is partial.** `sc_post_recent` only shows results of MCP-issued evaluations, not arbitrary `.postln` output from patterns or synths.  sclang doesn't expose its Post class's output stream over OSC. If you want to capture that too, wire your Pdefs to emit via `NetAddr("127.0.0.1", 57121).sendMsg("/mcpReply", 0, 1, "...")` explicitly.
- **Screenshots are full-screen.** Window-ID targeting on macOS needs assistive access permission most sessions don't have. If your terminal has been granted assistive access via System Settings → Privacy → Accessibility, you can tighten this later.

## Example prompts (for the MCP client)

- "Evaluate `SinOsc.ar(440).play` in SC and hush after 2 seconds"
- "What's the current value of `~ws.destName` in SC?"
- "Screenshot the SC IDE and describe what the bus view is showing"
- "Recompile the class library, then re-install the mcp listener"

## Related MCPs

| Repo | For |
|---|---|
| [`superclean-mcp`](https://github.com/Ziforge/superclean-mcp) | SuperClean pattern control (Pdef.play, hush, list) — layered on top of this |
| [`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 (fork of zerubeus) |

## License

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