# 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](https://github.com/elk-audio/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
1. Clone the repository:
```bash
git clone https://github.com/YOUR_USERNAME/sushi-mcp.git
cd sushi-mcp
```
2. Create and activate a virtual environment:
```bash
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
```
3. Install dependencies:
```bash
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
1. Start the MCP server:
```bash
python sushi_mcp_server.py
```
2. 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`):
```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:
```bash
python -m grpc_tools.protoc -I. --python_out=. --grpc_python_out=. sushi_rpc.proto
```
### Adding New Features
1. Add new tool functions decorated with `@mcp.tool()`
2. Implement the gRPC calls to Sushi
3. Add appropriate error handling
4. 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](https://github.com/elk-audio/sushi) audio engine by Elk Audio
- Uses the [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) specification
