Skip to main content
Glama

SuperCollider MCP Server

by BradA1878
README.md8.47 kB
# 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](https://supercollider.github.io/downloads)) ### 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)**: ```bash sudo apt-get install supercollider ``` **Linux (Arch)**: ```bash 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: ```bash export SCLANG_PATH="/path/to/sclang" # Optional: export SCSYNTH_PATH="/path/to/scsynth" ``` ## Installation ```bash 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` ```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) ```bash npm run inspector ``` ### Standalone Development ```bash 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. ```typescript // 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. ```typescript // 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" ```json { "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 ```json { "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. ```json { "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. ```json { "code": "{ SinOsc.ar([440, 442], 0, 0.2) }.play;" } ``` --- ### Recording #### `sc_record_start` Start recording audio output to a file. ```json { "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)](https://brada1878.github.io/model-exchange-framework/) 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 ```bash npm run build ``` ### Watch mode (for development) ```bash npm run dev ``` ### Type checking ```bash npx tsc --noEmit ``` --- ## Troubleshooting ### "sclang not found" Make sure SuperCollider is installed and `sclang` is in your PATH: ```bash which sclang # Should show the path to sclang ``` On macOS, you may need to add to your PATH: ```bash 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.

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/BradA1878/mcp-wave'

If you have feedback or need assistance with the MCP directory API, please join our Discord server