SuperCollider MCP Server

A Model Context Protocol (MCP) server for controlling SuperCollider audio synthesis. This server enables AI assistants like Claude to generate and control real-time audio synthesis through natural language descriptions.

Features

• Natural Language Sound Synthesis: Describe sounds in plain English and have them synthesized in real-time
• 10 Built-in Synth Types: sine, pluck, bell, bass, pad, kick, snare, hihat, atmosphere, sweep
• Server Lifecycle Management: Boot, quit, and monitor SuperCollider server status
• Pattern Sequencing: Create rhythmic patterns and melodic sequences
• Audio Recording: Record synthesis output to files
• Raw Code Execution: Execute custom SuperCollider code for advanced control
• TypeScript & Type-Safe: Fully typed with Zod schema validation

Prerequisites

• Node.js 18+
• SuperCollider installed locally (download here)

Installing SuperCollider

macOS:

1. Download from https://supercollider.github.io/downloads

2. Drag `SuperCollider.app` to `/Applications/`

3. The MCP server will auto-detect it

Linux (Ubuntu/Debian):

sudo apt-get install supercollider

Linux (Arch):

sudo pacman -S supercollider

Windows:

1. Download installer from https://supercollider.github.io/downloads

2. Run the installer

3. The MCP server will auto-detect it

Custom Installation Path

If SuperCollider is installed in a non-standard location, set the environment variable:

export SCLANG_PATH="/path/to/sclang"
# Optional: export SCSYNTH_PATH="/path/to/scsynth"

Installation

npm install
npm run build

Usage

With Claude Desktop

Add to your Claude Desktop config file:

macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`

{
  "mcpServers": {
    "supercollider": {
      "command": "node",
      "args": ["/absolute/path/to/supercollider-mcp/dist/index.js"]
    }
  }
}

Windows: `%APPDATA%\Claude\claude_desktop_config.json`

Restart Claude Desktop after updating the config.

With MCP Inspector (for testing)

npm run inspector

Standalone Development

npm run dev

Available Tools

Setup & Diagnostics

`sc_health_check`

Check if SuperCollider is installed and configured correctly. Run this first if you have any issues.

// No parameters required
sc_health_check()

Returns:

• ✅ Success: SuperCollider path and confirmation
• ❌ Error: Installation instructions for your platform

Core Server Management

`sc_boot`

Boot the SuperCollider audio server. Must be called before any sound synthesis.

// No parameters required
sc_boot()

`sc_quit`

Quit the SuperCollider server and clean up resources.

`sc_status`

Get current server status including CPU usage and running synths.

Sound Synthesis

`sc_play_synth` (Recommended for AI)

Play a synthesized sound based on a natural language description. This is the primary tool for sound generation.

Examples:

• "play a bell sound at C4"
• "play a low bass tone for 2 seconds"
• "play a bright plucked string"
• "play a soft atmospheric pad"
• "play a short snare"
• "play a sweep from 100hz to 2000hz over 3 seconds"

{
  "description": "play a bell sound at C5 for 2 seconds"
}

The parser understands:

• Note names: C4, D#5, Bb3, etc.
• Frequencies: 440hz, 880hz, etc.
• Descriptive terms: high, low, bright, deep, soft, loud, short, long
• Synth types: bell, bass, pad, pluck, kick, snare, hihat, sweep, atmosphere
• Spatial terms: left, right (for panning)

`sc_play_synth_advanced`

Play a specific synth with explicit parameters for precise control.

Available synths: sine, pluck, bell, bass, pad, kick, snare, hihat, atmosphere, sweep

{
  "synthName": "bell",
  "freq": 523.25,
  "amp": 0.4,
  "duration": 2,
  "pan": 0.5
}

Parameters:

• `freq`: Frequency in Hz (default: 440)
• `amp`: Amplitude 0-1 (default: 0.3)
• `duration`: Duration in seconds (default: 1)
• `pan`: Pan position -1 (left) to 1 (right) (default: 0)
• `decay`: Decay time for pluck synth (default: 2)
• `cutoff`: Filter cutoff frequency for bass/pad
• `startFreq`, `endFreq`: For sweep synth

`sc_play_pattern`

Play a rhythmic pattern or sequence of notes.

{
  "pattern": [
    { "synth": "kick", "delay": 0 },
    { "synth": "snare", "delay": 0.5 },
    { "synth": "hihat", "delay": 0.25, "amp": 0.2 },
    { "synth": "hihat", "delay": 0.25, "amp": 0.2 },
    { "synth": "kick", "delay": 0.5 }
  ]
}

`sc_stop_all`

Stop all currently playing synths immediately.

Advanced Control

`sc_execute`

Execute raw SuperCollider code for custom synthesis and advanced control.

{
  "code": "{ SinOsc.ar([440, 442], 0, 0.2) }.play;"
}

Recording

`sc_record_start`

Start recording audio output to a file.

{
  "filename": "my-composition.wav"
}

Files are saved to the `recordings/` directory.

`sc_record_stop`

Stop the current recording.

Example Conversation Flow

User: "I want to hear a dreamy bell sound"

Claude:

Using sc_boot to start SuperCollider server...
Using sc_play_synth with description "bell sound at C5"...

The server will synthesize a bell-like tone using FM synthesis.

User: "Now play a bass line"

Claude:

Using sc_play_pattern with:
- Low bass notes
- Rhythmic timing

Synth Descriptions

sine

Pure sine wave tone. Clean and simple.

pluck

Plucked string simulation using the Karplus-Strong algorithm. Good for guitar-like sounds.

bell

Bell-like FM synthesis. Bright and metallic.

bass

Filtered sawtooth wave. Deep bass tones.

pad

Warm, detuned sawtooth pad. Good for ambient backgrounds.

kick

Kick drum with frequency envelope.

snare

Snare drum with noise and tone components.

hihat

Hi-hat cymbal using filtered noise.

atmosphere

Atmospheric noise with slow filter modulation. Good for ambient textures.

sweep

Frequency sweep/riser. Goes from startFreq to endFreq over duration.

Architecture

src/
├── index.ts           # MCP server implementation
├── supercollider.ts   # SuperCollider process management
└── synth-library.ts   # Synth definitions and NLP parser

Key Components:

• SuperColliderServer: Manages sclang process lifecycle and code execution
• Synth Library: Pre-defined SynthDefs for common sound types
• NLP Parser: Converts natural language to synth parameters
• MCP Tools: Exposed functions for AI interaction

Integration with MXF

This server is designed to work with the Model Exchange Framework (MXF) for multi-agent music composition. Future enhancements will include:

• Event-driven synthesis triggered by MXF events
• Shared memory for musical context (key, tempo, style)
• Coordination with MIDI MCP server for external control
• Agent collaboration on compositional tasks

Development

Build

npm run build

Watch mode (for development)

npm run dev

Type checking

npx tsc --noEmit

Troubleshooting

"sclang not found"

Make sure SuperCollider is installed and `sclang` is in your PATH:

which sclang  # Should show the path to sclang

On macOS, you may need to add to your PATH:

export PATH="/Applications/SuperCollider.app/Contents/MacOS:$PATH"

Server won't boot

• Check that no other SuperCollider instances are running
• Verify SuperCollider works standalone: `sclang`
• Check server output in the MCP logs

No sound output

• Verify your system audio is working
• Check SuperCollider audio device settings
• Try `Server.default.options.device = "your-device-name";` via `sc_execute`

Future Enhancements

• [ ] Real-time parameter modulation
• [ ] MIDI input/output integration
• [ ] Sample playback and manipulation
• [ ] Effects processing (reverb, delay, filters)
• [ ] Visual waveform/spectrum display
• [ ] Multi-server support (supernova)
• [ ] Preset management
• [ ] MXF event bus integration
• [ ] Collaborative composition with multiple agents

License

MIT

Contributing

Contributions welcome! Please open an issue or PR.