README - SuperCollider OSC MCP 🎛️ by tok

SuperCollider OSC MCP 🎛️

A Model Context Protocol (MCP) server for SuperCollider using Open Sound Control (OSC).

Description

This project provides a Python interface for communicating with SuperCollider via OSC messages, integrated with AI development environments using the Model Context Protocol (MCP). It allows for programmatic control of audio synthesis and processing in SuperCollider from various AI coding assistants.

Features

Send OSC messages to SuperCollider
Play procedurally generated melodies with different scales
Create rhythmic drum patterns
Advanced sound design with synthesizers, effects, and modulation
Ambient soundscape generation
Granular synthesis and layered instruments
Chord progression generation with different voicing styles
Flexible integration with multiple AI development- and assistance environments

The available tools were not created with direct usage in mind and may therefore stay limited in scope. They are intended to serve as a codebase with templates for further customization and project specific implementation by your AI agent after giving it full access to the code.

Installation

Prerequisites

Python 3.12 or higher
SuperCollider 3.13.1
- Ensure server is running on port 57110
UV - Fast Python package manager

Installing UV (Python Package Manager)

# Install UV on macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install UV on Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Project Installation

# Clone the repository
git clone https://github.com/tok/supercollidermcp.git
cd supercollidermcp

# Install with UV
uv pip install -e .

Usage

AI Development Environment Integration

Claude Desktop

Configure in Claude Desktop settings:

"Super-Collider-OSC-MCP": {
  "command": "uv",
  "args": [
    "run",
    "--with",
    "mcp[cli],python-osc",
    "mcp",
    "run",
    "path/to/server.py"
  ]
}

Roo Code / Cline

Add to mcp.json:

{
  "mcpServers": {
    "Super-Collider-OSC-MCP": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp[cli],python-osc",
        "mcp",
        "run",
        "path/to/server.py"
      ]
    }
  }
}

AI Assistant Tool Adaptation

Workspace Integration for Dynamic Tool Creation

To enable advanced functionality, it is recommended to add server.py to the AI assistant's workspace. This allows the AI to:

Dynamically understand the project's structure
Analyze and modify the existing sound generation tools
Create new OSC-based tools on demand
Adapt the Python code to extend functionality

Integration Steps

Add the entire project directory to the AI assistant's workspace
Ensure server.py is visible and accessible to the AI
Provide context about the MCP and OSC communication protocols
Allow the AI to inspect and modify the project files

Recommended Workspace Structure

supercollidermcp/
│
├── server.py              # Main MCP server with all sound generation tools including advanced synthesis, soundscape and generative rhythm tools
├── supercollidermcp/
│   ├── osc.py             # SuperCollider OSC client
│   ├── melody.py          # Melody generation utilities
│   ├── rhythm.py          # Rhythm pattern utilities
│   └── ...
└── README.md

Note: The ability to modify tools dynamically depends on the specific capabilities of the AI assistant and its integration with the Model Context Protocol.

Local Testing and Development

The project has been tested with Claude Desktop and locally using Roo Code with:

Ollama - Local AI model server
DeepCoder (open-source model)

Available Commands

Once configured, the assistant can use a variety of tools:

Basic Sound Generation

play_example_osc - Play a simple example sound with frequency modulation
play_melody - Create a procedurally generated melody using a specified scale and tempo
create_drum_pattern - Play drum patterns in various styles (four_on_floor, breakbeat, shuffle, random)
play_synth - Play a single note with different synthesizer types (sine, saw, square, noise, fm, pad) and effects
create_sequence - Create a musical sequence from a pattern string with note length variations

Advanced Synthesis

create_lfo_modulation - Apply modulation to synthesizer parameters (frequency, amplitude, filter, pan)
create_layered_synth - Create rich sounds with multiple detuned oscillator layers and stereo spread
create_granular_texture - Create textures using granular synthesis with controllable density and pitch variation
create_chord_progression - Play chord progressions with different voicing styles (pad, staccato, arpeggio, power)

Soundscape Generation

create_ambient_soundscape - Generate evolving ambient textures with different moods (calm, dark, bright, mysterious, chaotic)
create_generative_rhythm - Create evolving rhythmic patterns in different styles (minimal, techno, glitch, jazz, ambient)

Example Usage in Claude

Here are some examples of how to use these tools in Claude:

// Basic melody
play_melody(scale="pentatonic", tempo=110)

// Layered synth with effects
create_layered_synth(base_note="F3", num_layers=4, detune=0.2, effects={"reverb": 0.6, "delay": 0.3}, duration=4.0)

// Ambient soundscape
create_ambient_soundscape(duration=20, density=0.6, pitch_range="medium", mood="mysterious")

// Chord progression
create_chord_progression(progression="Cmaj7-Am7-Dm7-G7", style="arpeggio", tempo=100, duration_per_chord=2.0)

Testing Locally

You can test the functionality directly by running:

python -m mcp.run server.py

You can also use the command-line interface:

# Play a note
sc-osc note --freq 440 --amp 0.5 --duration 2.0

# Play a scale
sc-osc scale --scale minor --tempo 100 --direction both

# Generate and play a melody
sc-osc melody --scale blues --tempo 120 --notes 16

# Play a drum pattern
sc-osc drums --pattern breakbeat --beats 32 --tempo 140

About SuperCollider

SuperCollider is a platform for audio synthesis and algorithmic composition, used by musicians, artists, and researchers working with sound. It consists of:

A real-time audio server with hundreds of unit generators for synthesis and signal processing
A cross-platform interpreted programming language (sclang)
A flexible scheduling system for precise timing of musical events

This project communicates with SuperCollider's audio server using OSC messages to control synthesizers and create sound patterns.

External Security Assessment

Development

The project uses FastMCP for handling Claude's requests and the python-osc library for communicating with SuperCollider. For more information about the Model Context Protocol, visit https://modelcontextprotocol.io/.

Contributing

Contributions are welcome! Please submit Pull Requests with:

New sound generation tools
Improved integration methods
Bug fixes and optimizations

License

This project is licensed under the MIT License - see the LICENSE file for details.

SuperColliderMCP