README - sushi-mcp by nagarjun226

Sushi MCP Server

An MCP (Model Context Protocol) server for controlling Sushi audio engine via gRPC. This allows AI assistants to interact with and control Sushi-powered audio devices and applications.

Overview

Sushi MCP Server provides a bridge between AI assistants and the Sushi audio engine, enabling:

Real-time audio processing control
Parameter automation
MIDI routing and control
Track and processor management
Preset management
Audio routing configuration

Features

System Control

Get Sushi version and build information
Query audio channel counts

Transport Control

Control playback (play, stop, record)
Set tempo and time signature
Manage sync modes (internal, MIDI, Link)

Track & Processor Management

List and manage tracks
Add/remove audio processors
Control processor parameters
Bypass/enable processors
Save and load presets

Audio Routing

Configure input/output connections
Route audio between tracks and engine channels

MIDI Control

Connect MIDI keyboards to tracks
Map MIDI CC to parameters
Send MIDI notes programmatically
Configure MIDI routing

Real-time Updates

Subscribe to parameter changes
Watch specific parameters for updates
Get real-time notifications

Prerequisites

Python 3.13 or higher
A running instance of Sushi with gRPC enabled
The Sushi gRPC interface exposed (default port: 51051)

Installation

Clone the repository:

git clone https://github.com/YOUR_USERNAME/sushi-mcp.git
cd sushi-mcp

Create and activate a virtual environment:

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

Install dependencies:

pip install -e .

Configuration

The server includes a sample configuration file default_config_sushi.json that demonstrates a typical Sushi setup with:

8 playback tracks with WAV streamers
2 input tracks with various effects processors
Audio routing configurations
Initial parameter states

You can modify this file to match your Sushi configuration.

Usage

Running the MCP Server

Start the MCP server:

python sushi_mcp_server.py

The server runs in stdio mode and waits for MCP client connections.

Connecting from Claude Desktop

Add the following to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "sushi-control": {
      "command": "python",
      "args": ["/path/to/sushi-mcp/sushi_mcp_server.py"],
      "env": {}
    }
  }
}

Basic Usage Examples

Once connected, you can use natural language to control Sushi:

"Connect to Sushi at 192.168.1.100"
"Show me all tracks"
"Set the tempo to 120 BPM"
"Add a reverb to track 1"
"Set the gain parameter of the input processor to 0.8"
"Connect MIDI channel 1 to the synthesizer track"
"Save the current state as a preset"

Available MCP Tools

Connection

set_sushi_server - Set the IP address and port of the Sushi server

System Information

get_sushi_info - Get Sushi version and system information
get_available_plugins - List available internal plugins

Transport Control

get_transport_info - Get current transport state
set_tempo - Set the tempo in BPM
set_playing_mode - Control playback (STOPPED, PLAYING, RECORDING)

Track Management

get_all_tracks - List all tracks
get_track_processors - List processors on a track
add_processor_to_track - Add a processor to a track
remove_processor_from_track - Remove a processor

Parameter Control

get_processor_parameters - List all parameters for a processor
set_parameter_value - Set a parameter value
bypass_processor - Bypass or enable a processor

Audio Routing

get_track_connections - Get audio connections for a track
connect_input_to_track - Route audio input to a track
connect_track_to_output - Route track to audio output

MIDI Control

get_midi_ports - Get MIDI port information
get_midi_keyboard_connections - List MIDI keyboard connections
connect_midi_keyboard_to_track - Connect MIDI input to track
connect_midi_cc_to_parameter - Map MIDI CC to parameter
send_note_on / send_note_off - Send MIDI notes

Preset Management

save_processor_preset - Save processor state as preset
load_processor_preset - Load a saved preset
list_presets - List all saved presets
snapshot_all_tracks - Save complete session state
load_snapshot - Restore complete session state

Real-time Monitoring

subscribe_to_parameter_updates - Enable real-time updates
watch_parameter - Monitor specific parameter
get_parameter_updates - Get recent parameter changes

Project Structure

sushi-mcp/
├── sushi_mcp_server.py      # Main MCP server implementation
├── sushi_rpc.proto          # gRPC protocol definition
├── sushi_rpc_pb2.py         # Generated protobuf code
├── sushi_rpc_pb2_grpc.py    # Generated gRPC code
├── default_config_sushi.json   # Sample Sushi configuration
├── pyproject.toml           # Project dependencies
├── presets/                 # Saved presets directory
└── README.md                # This file

Development

Regenerating gRPC Code

If you need to update the gRPC interface:

python -m grpc_tools.protoc -I. --python_out=. --grpc_python_out=. sushi_rpc.proto

Adding New Features

Add new tool functions decorated with @mcp.tool()
Implement the gRPC calls to Sushi
Add appropriate error handling
Update this README with the new functionality

Troubleshooting

Connection Issues

Ensure Sushi is running with gRPC enabled
Check that the gRPC port (default 51051) is accessible
Verify the IP address and port with set_sushi_server

Parameter Ranges

The server validates parameter values against their defined ranges
Use get_processor_parameters to see valid ranges

MIDI Channels

MIDI channels are 1-16 (17 for omni mode)
Channel 0 is not valid in the MIDI specification

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

License

This project is licensed under the same terms as your other projects. Please add appropriate license file.

Acknowledgments

Built for the Sushi audio engine by Elk Audio
Uses the MCP (Model Context Protocol) specification