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

1. Add the entire project directory to the AI assistant's workspace
2. Ensure server.py is visible and accessible to the AI
3. Provide context about the MCP and OSC communication protocols
4. 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

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

Advanced Synthesis

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

Soundscape Generation

10. create_ambient_soundscape - Generate evolving ambient textures with different moods (calm, dark, bright, mysterious, chaotic)
11. 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.

Additional Resources

• Model Context Protocol
• SuperCollider Official Website