OSC MCP Server

A Model Context Protocol (MCP) server for controlling digital mixers (Behringer X32, Midas M32, etc.) via OSC (Open Sound Control). This allows you to control your mixer through chat commands in Claude Desktop.

Features

🎚️ Fader Control: Set and get fader levels for all channels, buses, aux, matrix, and main LR
🔇 Mute/Unmute: Control muting for channels, buses, aux, matrix, and main mix
🎛️ Pan Control: Adjust stereo positioning for channels, buses, aux, and main mix
🎵 EQ Control: Full 4-band parametric EQ with frequency, Q, gain, and on/off control
🎚️ Dynamics: Complete gate and compressor control with attack, release, threshold, and ratio
🔊 Aux Sends: Control sends from channels to mix buses and aux outputs
📸 Scenes: Recall, save, and manage scenes with custom names
🎛️ Bus Control: Full control over mix buses (1-16) with faders, pan, mute, and naming
🔊 Aux Control: Control aux outputs (1-6) with faders, pan, and mute
🎚️ Matrix Control: Control matrix outputs (1-6) with faders and mute
🎵 Effects: Control effects (1-8) with on/off, mix, and parameter adjustment
🔌 Routing: Configure channel input sources
📝 Naming: Set and get names for channels and buses
🔧 Custom Commands: Send any OSC command to the mixer
📊 Status Monitoring: Get mixer status and information

Installation

Prerequisites

Node.js 18 or higher
A digital mixer (Behringer X32, Midas M32, etc.) on your network
Claude Desktop app

Setup

Clone or navigate to this repository:

cd path/to/osc-mcp

Install dependencies:

npm install

Build the project:

npm run build

Configuration

Environment Variables

You can configure the OSC connection using environment variables:

OSC_HOST: IP address of your mixer (default: 192.168.1.70)
OSC_PORT: OSC port of your mixer (default: 10023)

Claude Desktop Configuration

Add the following to your Claude Desktop configuration file:

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

{
  "mcpServers": {
      "osc": {
      "command": "node",
      "args": [
        "/path/to/osc-mcp/dist/index.js"
      ],
      "env": {
        "OSC_HOST": "192.168.1.70",
        "OSC_PORT": "10023"
      }
    }
  }
}

Important: Replace the IP address 192.168.1.70 with your mixer's actual IP address!

Finding Your Mixer IP Address

On your mixer, press the SETUP button
Navigate to Network settings
Note the IP address shown

Usage Examples

Once configured in Claude Desktop, you can use natural language to control your mixer:

Basic Fader Control

"Set channel 1 fader to 75%"
"What's the current level of channel 5?"
"Set the main fader to 80%"
"Set bus 3 fader to 60%"
"What's the aux 2 fader level?"

Muting

"Mute channel 3"
"Unmute channel 7"
"Mute bus 5"
"Unmute the main mix"

Pan Control

"Pan channel 2 to the left"
"Center the pan on channel 4"
"Pan channel 8 to the right"
"Set bus 2 pan to center"

EQ

"Boost channel 1 EQ band 2 by 3dB"
"Cut channel 5 EQ band 4 by 6dB"
"Set channel 3 EQ band 1 frequency to 100Hz"
"Set channel 2 EQ band 3 Q to 2.5"
"Enable EQ on channel 1"

Dynamics

"Set channel 1 gate threshold to -40dB"
"Set channel 3 compressor with -20dB threshold and 4:1 ratio"
"Set channel 2 compressor attack to 50%"
"Set channel 4 compressor release to 30%"
"Enable gate on channel 5"

Aux Sends

"Send channel 1 to bus 3 at 50%"
"What's the send level from channel 2 to bus 5?"
"Send channel 4 to aux 2 at 75%"

Bus Control

"Set bus 1 fader to 70%"
"Mute bus 3"
"Pan bus 2 to the right"
"Name bus 4 'Monitor'"

Effects

"Enable effect 1"
"Set effect 2 mix to 50%"
"Set effect 3 parameter 5 to 75%"

Routing

"Set channel 1 source to input 5"
"What's the source for channel 3?"

Scenes

"Recall scene 5"
"Save the current mix as scene 10"
"Save scene 15 as 'Concert Setup'"
"What's the name of scene 3?"

Channel Management

"Name channel 1 'Lead Vocal'"
"What's the name of channel 5?"
"Set channel 2 color to 3"

Custom Commands

"Send OSC command /ch/01/config/name with value 'Vocals'"
"Send OSC command /ch/05/mix/fader with value 0.75"
"Send OSC command /bus/03/mix/on with value 1"
"Send OSC command /fx/01/on with value 1"

Available Tools

The MCP server exposes 50+ tools for comprehensive mixer control:

Channel Controls (9 tools)

osc_set_fader - Set channel fader level (0.0-1.0)
osc_get_fader - Get current channel fader level
osc_mute_channel - Mute/unmute a channel
osc_get_mute - Get mute status of a channel
osc_set_pan - Set channel pan (-1.0 to 1.0)
osc_get_pan - Get channel pan position
osc_set_channel_name - Set channel name
osc_get_channel_name - Get channel name
osc_set_channel_source / osc_get_channel_source - Configure input source

EQ Controls (5 tools)

osc_set_eq - Set EQ band gain (-15dB to +15dB)
osc_get_eq - Get EQ band gain
osc_set_eq_frequency - Set EQ band frequency
osc_set_eq_q - Set EQ band Q factor
osc_set_eq_on - Enable/disable EQ

Dynamics Controls (7 tools)

osc_set_gate - Set gate threshold (-80dB to 0dB)
osc_get_gate - Get gate threshold
osc_set_gate_on - Enable/disable gate
osc_set_compressor - Set compressor threshold and ratio
osc_set_compressor_attack - Set compressor attack time
osc_set_compressor_release - Set compressor release time
osc_set_compressor_on - Enable/disable compressor

Bus Controls (5 tools)

osc_set_bus_fader - Set bus fader level
osc_get_bus_fader - Get bus fader level
osc_mute_bus - Mute/unmute a bus
osc_set_bus_pan - Set bus pan position
osc_set_bus_name - Set bus name

Aux Controls (4 tools)

osc_set_aux_fader - Set aux fader level
osc_get_aux_fader - Get aux fader level
osc_mute_aux - Mute/unmute an aux output
osc_set_aux_pan - Set aux pan position

Sends (3 tools)

osc_send_to_bus - Set send level from channel to bus
osc_get_send_to_bus - Get send level from channel to bus
osc_send_to_aux - Set send level from channel to aux

Main Mix (4 tools)

osc_set_main_fader - Set main LR fader level
osc_get_main_fader - Get main LR fader level
osc_mute_main - Mute/unmute main LR mix
osc_set_main_pan - Set main LR pan position

Matrix (2 tools)

osc_set_matrix_fader - Set matrix fader level
osc_mute_matrix - Mute/unmute a matrix output

Effects (3 tools)

osc_set_effect_on - Enable/disable an effect
osc_set_effect_mix - Set effect mix level
osc_set_effect_param - Set effect parameter value

Scenes (3 tools)

osc_scene_recall - Recall a saved scene (1-100)
osc_scene_save - Save current mixer state as a scene
osc_get_scene_name - Get scene name

Status & Custom (2 tools)

osc_get_mixer_status - Get mixer status and info
osc_custom_command - Send custom OSC command

Technical Details

Dependencies:

@modelcontextprotocol/sdk - MCP server framework
osc-js - OSC protocol implementation (v2.4.1)
TypeScript - Type-safe development

OSC Communication:

Protocol: UDP
Default Port: 10023
Bidirectional communication with mixer
Automatic connection keep-alive (/xremote every 9 seconds)
Uses osc-js library with DatagramPlugin for UDP communication

Supported Mixer Models:

Behringer X32
Behringer X32 Compact
Behringer X32 Producer
Behringer X32 Rack
Midas M32 (compatible)

Development

Watch Mode

npm run dev

Build

npm run build

Run Directly

npm start

Troubleshooting

Connection Issues

Verify network connectivity: Ping your mixer
```
ping 192.168.1.70
```
Check OSC settings: Ensure OSC is enabled on the mixer
Firewall: Make sure your firewall allows UDP traffic on port 10023
Check Claude Desktop logs:
- macOS: ~/Library/Logs/Claude/

Common Issues

"Timeout waiting for response": The mixer might not be responding. Check network connection and mixer settings.
"Connection refused": Verify the IP address and port are correct.
Tools not appearing in Claude: Restart Claude Desktop after updating the config file.

Custom OSC Commands

The osc_custom_command tool allows you to send any OSC command to the mixer. This is useful for accessing features not covered by the standard tools.

Examples

Setting Channel Names

{
  "address": "/ch/01/config/name",
  "value": "Lead Vocal"
}

Setting Channel Colors

{
  "address": "/ch/05/config/color",
  "value": 3
}

Controlling Channel Preamp Gain

{
  "address": "/ch/03/preamp/trim",
  "value": 0.5
}

Setting High-Pass Filter

{
  "address": "/ch/02/hpf",
  "value": 1
}

Controlling Insert Effects

{
  "address": "/ch/04/insert/on",
  "value": 1
}

Setting Bus Configuration

{
  "address": "/bus/02/config/name",
  "value": "Monitor"
}

Controlling Effects Parameters

{
  "address": "/fx/01/par/01",
  "value": 0.75
}

Setting Matrix Configuration

{
  "address": "/mtx/01/config/name",
  "value": "Recording"
}

Controlling Talkback

{
  "address": "/-stat/talk",
  "value": 1
}

Setting Solo

{
  "address": "/ch/01/mix/solo",
  "value": 1
}

Commands Without Values

Some OSC commands don't require a value:

{
  "address": "/-stat/solosw"
}

Common OSC Addresses

Channel Configuration

/ch/{nn}/config/name - Channel name (string)
/ch/{nn}/config/color - Channel color (0-15)
/ch/{nn}/config/source - Input source (0-63)
/ch/{nn}/preamp/trim - Preamp gain (0.0-1.0)
/ch/{nn}/preamp/hpon - High-pass filter on (0/1)
/ch/{nn}/preamp/hpf - High-pass filter frequency (0.0-1.0)

Channel Mix

/ch/{nn}/mix/solo - Solo channel (0/1)
/ch/{nn}/mix/st - Send to stereo (0.0-1.0)
/ch/{nn}/mix/mlevel - Monitor level (0.0-1.0)

Insert Effects

/ch/{nn}/insert/on - Insert effect on (0/1)
/ch/{nn}/insert/pos - Insert position (0-3)

Bus Configuration

/bus/{nn}/config/name - Bus name (string)
/bus/{nn}/config/color - Bus color (0-15)
/bus/{nn}/config/mono - Mono bus (0/1)

Effects

/fx/{nn}/on - Effect on (0/1)
/fx/{nn}/mix - Effect mix (0.0-1.0)
/fx/{nn}/par/{nn} - Effect parameter (0.0-1.0)

Matrix

/mtx/{nn}/config/name - Matrix name (string)
/mtx/{nn}/config/color - Matrix color (0-15)

System

/-stat/talk - Talkback (0/1)
/-stat/solosw - Solo switch (no value)
/-stat/rtn - Return solo (0/1)

Note: Replace {nn} with zero-padded channel/bus/effect numbers (e.g., 01, 02, 15).

Value Types

The osc_custom_command tool automatically detects value types:

Numbers: Automatically sent as float or integer
Strings: Sent as OSC string type
Arrays: Can be used for multiple arguments

Example with multiple arguments:

{
  "address": "/custom/path",
  "value": [0.5, "text", 42]
}

X32 OSC Reference

For advanced usage and complete OSC command reference, refer to the Behringer X32 OSC Protocol.

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

OSC MCP Server

Features

🎚️ Fader Control: Set and get fader levels for all channels, buses, aux, matrix, and main LR
🔇 Mute/Unmute: Control muting for channels, buses, aux, matrix, and main mix
🎛️ Pan Control: Adjust stereo positioning for channels, buses, aux, and main mix
🎵 EQ Control: Full 4-band parametric EQ with frequency, Q, gain, and on/off control
🎚️ Dynamics: Complete gate and compressor control with attack, release, threshold, and ratio
🔊 Aux Sends: Control sends from channels to mix buses and aux outputs
📸 Scenes: Recall, save, and manage scenes with custom names
🎛️ Bus Control: Full control over mix buses (1-16) with faders, pan, mute, and naming
🔊 Aux Control: Control aux outputs (1-6) with faders, pan, and mute
🎚️ Matrix Control: Control matrix outputs (1-6) with faders and mute
🎵 Effects: Control effects (1-8) with on/off, mix, and parameter adjustment
🔌 Routing: Configure channel input sources
📝 Naming: Set and get names for channels and buses
🔧 Custom Commands: Send any OSC command to the mixer
📊 Status Monitoring: Get mixer status and information

Installation

Prerequisites

Node.js 18 or higher
A digital mixer (Behringer X32, Midas M32, etc.) on your network
Claude Desktop app

Setup

Clone or navigate to this repository:

cd path/to/osc-mcp

Install dependencies:

npm install

Build the project:

npm run build

Configuration

Environment Variables

You can configure the OSC connection using environment variables:

OSC_HOST: IP address of your mixer (default: 192.168.1.70)
OSC_PORT: OSC port of your mixer (default: 10023)

Claude Desktop Configuration

Add the following to your Claude Desktop configuration file:

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

{
  "mcpServers": {
      "osc": {
      "command": "node",
      "args": [
        "/path/to/osc-mcp/dist/index.js"
      ],
      "env": {
        "OSC_HOST": "192.168.1.70",
        "OSC_PORT": "10023"
      }
    }
  }
}

Important: Replace the IP address 192.168.1.70 with your mixer's actual IP address!

Finding Your Mixer IP Address

On your mixer, press the SETUP button
Navigate to Network settings
Note the IP address shown

Usage Examples

Once configured in Claude Desktop, you can use natural language to control your mixer:

Basic Fader Control

"Set channel 1 fader to 75%"
"What's the current level of channel 5?"
"Set the main fader to 80%"
"Set bus 3 fader to 60%"
"What's the aux 2 fader level?"

Muting

"Mute channel 3"
"Unmute channel 7"
"Mute bus 5"
"Unmute the main mix"

Pan Control

"Pan channel 2 to the left"
"Center the pan on channel 4"
"Pan channel 8 to the right"
"Set bus 2 pan to center"

EQ

"Boost channel 1 EQ band 2 by 3dB"
"Cut channel 5 EQ band 4 by 6dB"
"Set channel 3 EQ band 1 frequency to 100Hz"
"Set channel 2 EQ band 3 Q to 2.5"
"Enable EQ on channel 1"

Dynamics

"Set channel 1 gate threshold to -40dB"
"Set channel 3 compressor with -20dB threshold and 4:1 ratio"
"Set channel 2 compressor attack to 50%"
"Set channel 4 compressor release to 30%"
"Enable gate on channel 5"

Aux Sends

"Send channel 1 to bus 3 at 50%"
"What's the send level from channel 2 to bus 5?"
"Send channel 4 to aux 2 at 75%"

Bus Control

"Set bus 1 fader to 70%"
"Mute bus 3"
"Pan bus 2 to the right"
"Name bus 4 'Monitor'"

Effects

"Enable effect 1"
"Set effect 2 mix to 50%"
"Set effect 3 parameter 5 to 75%"

Routing

"Set channel 1 source to input 5"
"What's the source for channel 3?"

Scenes

"Recall scene 5"
"Save the current mix as scene 10"
"Save scene 15 as 'Concert Setup'"
"What's the name of scene 3?"

Channel Management

"Name channel 1 'Lead Vocal'"
"What's the name of channel 5?"
"Set channel 2 color to 3"

Custom Commands

"Send OSC command /ch/01/config/name with value 'Vocals'"
"Send OSC command /ch/05/mix/fader with value 0.75"
"Send OSC command /bus/03/mix/on with value 1"
"Send OSC command /fx/01/on with value 1"

Available Tools

The MCP server exposes 50+ tools for comprehensive mixer control:

Channel Controls (9 tools)

osc_set_fader - Set channel fader level (0.0-1.0)
osc_get_fader - Get current channel fader level
osc_mute_channel - Mute/unmute a channel
osc_get_mute - Get mute status of a channel
osc_set_pan - Set channel pan (-1.0 to 1.0)
osc_get_pan - Get channel pan position
osc_set_channel_name - Set channel name
osc_get_channel_name - Get channel name
osc_set_channel_source / osc_get_channel_source - Configure input source

EQ Controls (5 tools)

osc_set_eq - Set EQ band gain (-15dB to +15dB)
osc_get_eq - Get EQ band gain
osc_set_eq_frequency - Set EQ band frequency
osc_set_eq_q - Set EQ band Q factor
osc_set_eq_on - Enable/disable EQ

Dynamics Controls (7 tools)

osc_set_gate - Set gate threshold (-80dB to 0dB)
osc_get_gate - Get gate threshold
osc_set_gate_on - Enable/disable gate
osc_set_compressor - Set compressor threshold and ratio
osc_set_compressor_attack - Set compressor attack time
osc_set_compressor_release - Set compressor release time
osc_set_compressor_on - Enable/disable compressor

Bus Controls (5 tools)

osc_set_bus_fader - Set bus fader level
osc_get_bus_fader - Get bus fader level
osc_mute_bus - Mute/unmute a bus
osc_set_bus_pan - Set bus pan position
osc_set_bus_name - Set bus name

Aux Controls (4 tools)

osc_set_aux_fader - Set aux fader level
osc_get_aux_fader - Get aux fader level
osc_mute_aux - Mute/unmute an aux output
osc_set_aux_pan - Set aux pan position

Sends (3 tools)

osc_send_to_bus - Set send level from channel to bus
osc_get_send_to_bus - Get send level from channel to bus
osc_send_to_aux - Set send level from channel to aux

Main Mix (4 tools)

osc_set_main_fader - Set main LR fader level
osc_get_main_fader - Get main LR fader level
osc_mute_main - Mute/unmute main LR mix
osc_set_main_pan - Set main LR pan position

Matrix (2 tools)

osc_set_matrix_fader - Set matrix fader level
osc_mute_matrix - Mute/unmute a matrix output

Effects (3 tools)

osc_set_effect_on - Enable/disable an effect
osc_set_effect_mix - Set effect mix level
osc_set_effect_param - Set effect parameter value

Scenes (3 tools)

osc_scene_recall - Recall a saved scene (1-100)
osc_scene_save - Save current mixer state as a scene
osc_get_scene_name - Get scene name

Status & Custom (2 tools)

osc_get_mixer_status - Get mixer status and info
osc_custom_command - Send custom OSC command

Technical Details

Dependencies:

@modelcontextprotocol/sdk - MCP server framework
osc-js - OSC protocol implementation (v2.4.1)
TypeScript - Type-safe development

OSC Communication:

Protocol: UDP
Default Port: 10023
Bidirectional communication with mixer
Automatic connection keep-alive (/xremote every 9 seconds)
Uses osc-js library with DatagramPlugin for UDP communication

Supported Mixer Models:

Behringer X32
Behringer X32 Compact
Behringer X32 Producer
Behringer X32 Rack
Midas M32 (compatible)

Development

Watch Mode

npm run dev

Build

npm run build

Run Directly

npm start

Troubleshooting

Connection Issues

Verify network connectivity: Ping your mixer
```
ping 192.168.1.70
```
Check OSC settings: Ensure OSC is enabled on the mixer
Firewall: Make sure your firewall allows UDP traffic on port 10023
Check Claude Desktop logs:
- macOS: ~/Library/Logs/Claude/

Common Issues

"Timeout waiting for response": The mixer might not be responding. Check network connection and mixer settings.
"Connection refused": Verify the IP address and port are correct.
Tools not appearing in Claude: Restart Claude Desktop after updating the config file.

Custom OSC Commands

The osc_custom_command tool allows you to send any OSC command to the mixer. This is useful for accessing features not covered by the standard tools.

Examples

Setting Channel Names

{
  "address": "/ch/01/config/name",
  "value": "Lead Vocal"
}

Setting Channel Colors

{
  "address": "/ch/05/config/color",
  "value": 3
}

Controlling Channel Preamp Gain

{
  "address": "/ch/03/preamp/trim",
  "value": 0.5
}

Setting High-Pass Filter

{
  "address": "/ch/02/hpf",
  "value": 1
}

Controlling Insert Effects

{
  "address": "/ch/04/insert/on",
  "value": 1
}

Setting Bus Configuration

{
  "address": "/bus/02/config/name",
  "value": "Monitor"
}

Controlling Effects Parameters

{
  "address": "/fx/01/par/01",
  "value": 0.75
}

Setting Matrix Configuration

{
  "address": "/mtx/01/config/name",
  "value": "Recording"
}

Controlling Talkback

{
  "address": "/-stat/talk",
  "value": 1
}

Setting Solo

{
  "address": "/ch/01/mix/solo",
  "value": 1
}

Commands Without Values

Some OSC commands don't require a value:

{
  "address": "/-stat/solosw"
}

Common OSC Addresses

Channel Configuration

/ch/{nn}/config/name - Channel name (string)
/ch/{nn}/config/color - Channel color (0-15)
/ch/{nn}/config/source - Input source (0-63)
/ch/{nn}/preamp/trim - Preamp gain (0.0-1.0)
/ch/{nn}/preamp/hpon - High-pass filter on (0/1)
/ch/{nn}/preamp/hpf - High-pass filter frequency (0.0-1.0)

Channel Mix

/ch/{nn}/mix/solo - Solo channel (0/1)
/ch/{nn}/mix/st - Send to stereo (0.0-1.0)
/ch/{nn}/mix/mlevel - Monitor level (0.0-1.0)

Insert Effects

/ch/{nn}/insert/on - Insert effect on (0/1)
/ch/{nn}/insert/pos - Insert position (0-3)

Bus Configuration

/bus/{nn}/config/name - Bus name (string)
/bus/{nn}/config/color - Bus color (0-15)
/bus/{nn}/config/mono - Mono bus (0/1)

Effects

/fx/{nn}/on - Effect on (0/1)
/fx/{nn}/mix - Effect mix (0.0-1.0)
/fx/{nn}/par/{nn} - Effect parameter (0.0-1.0)

Matrix

/mtx/{nn}/config/name - Matrix name (string)
/mtx/{nn}/config/color - Matrix color (0-15)

System

/-stat/talk - Talkback (0/1)
/-stat/solosw - Solo switch (no value)
/-stat/rtn - Return solo (0/1)

Note: Replace {nn} with zero-padded channel/bus/effect numbers (e.g., 01, 02, 15).

Value Types

The osc_custom_command tool automatically detects value types:

Numbers: Automatically sent as float or integer
Strings: Sent as OSC string type
Arrays: Can be used for multiple arguments

Example with multiple arguments:

{
  "address": "/custom/path",
  "value": [0.5, "text", 42]
}

X32 OSC Reference

For advanced usage and complete OSC command reference, refer to the Behringer X32 OSC Protocol.

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.