NUX MG-30

nux-mg30-mcp

An MCP server that lets an AI assistant (Claude Desktop or any other MCP client) control a NUX MG-30 guitar processor over USB MIDI.

Describe the sound you want in plain words ("tight Children of Bodom rhythm tone", "less fizz, more mids on the lead"), and the assistant picks models, turns knobs, saves and names presets on the unit.

Unofficial project. It is not affiliated with or endorsed by NUX / Cherub Technology. The preset protocol was reverse-engineered on firmware 5.0.2, and other firmware versions may differ. Writing presets overwrites slots on your device, so run backup_presets first.

What it can do

• Live editing: select a model in any block (35 amps, 24 cabs/IRs, 15 drives, 14 modulations, 8 delays, 6 reverbs, …), switch blocks on and off, set knobs by name (gain, middle, 1.2k, subd, …).
• Read presets: list all 128 presets with names and amps, decode any preset (name, signal chain, models, knob values), and read the edit buffer including unsaved edits.
• Write presets: save the edit buffer to any slot with a name, rename presets, and back up or restore presets to and from JSON files. Every write is verified by reading it back.
• Tone recipes: apply a whole tone from a JSON patch file. Examples are in examples/patches.

Requirements

• A NUX MG-30 connected over USB. The device shows up as a class-compliant MIDI port.
• Python 3.10+.
• An MCP client, for example Claude Desktop.

The server has to run on the computer the MG-30 is plugged into, because it needs direct access to the USB MIDI port. Development and testing were done on macOS; Linux and Windows should work through python-rtmidi, but they are untested.

Installation

The easiest way is uv: uvx downloads and runs the server, no manual setup needed.

Claude Desktop

Open Settings → Developer → Edit Config and add:

{
  "mcpServers": {
    "nux-mg30": {
      "command": "uvx",
      "args": ["nux-mg30-mcp"]
    }
  }
}

Restart Claude Desktop completely. The tools show up under the nux-mg30 server. If Claude cannot find uvx, use its absolute path (which uvx, typically ~/.local/bin/uvx).

Alternatively, install it with pipx install nux-mg30-mcp or pip install nux-mg30-mcp and use "command": "nux-mg30-mcp".

From source

git clone https://github.com/voronkovd/nux-mg30-mcp.git
cd nux-mg30-mcp
python3 -m venv .venv
.venv/bin/pip install -e .

Then use "command": "/absolute/path/to/nux-mg30-mcp/.venv/bin/nux-mg30-mcp" in the client config.

Optional check without any AI client: lower your volume, then run python scripts/midi_check.py. The script mutes the AMP block for 1.5 seconds and restores it.

Configuration

Variable	Default	Meaning
MG30_PORT	auto (MG-30 / NUX)	substring of the MIDI port name
MG30_CHANNEL	1	MIDI channel set on the device
MG30_DATA_DIR	~/.nux-mg30-mcp	where backups, patch files and logs are stored
MG30_DEVICE_MAP	bundled	path to a custom device_map.json
MG30_DEBUG_TOOLS	off	1 exposes low-level research tools

Put these under "env" in the MCP client config.

First steps

1. Ask the assistant to back up all presets (backup_presets).
2. Ask it to list presets to see what is where.
3. Pick a free or unimportant slot and describe a sound. For example: "Switch to 12C and build a Death 'Sound of Perseverance' rhythm tone, then save it as 'Chuck Rhythm'."

Tools

Tool	What it does
connect, list_midi_ports	find and open the MG-30
device_state	current preset, models, on/off and knobs of the edit buffer
set_model(block, model, on)	select a model by name or number
set_block(block, on)	switch a block on or off
set_knob(block, knob, value)	set a knob by label or index, 0..100
apply_patch(patch)	apply models, on/off and knobs for several blocks at once
select_preset(preset)	switch preset ('07A' or 0..127)
list_presets, preset_info(preset)	read and decode stored presets or the edit buffer
save_preset(preset, name)	save the edit buffer to a slot, verified by read-back
rename_preset(preset, name)	rename a stored preset
backup_presets, list_backups, restore_preset	full backup and single-preset restore
save_patch_file, list_patch_files, load_patch_file	tone recipes as JSON files

Blocks are wah, comp, efx, amp, eq, ng (gate), mod, dly, rvb, ir (cab) and sendreturn. Common aliases such as delay, reverb, cab and gate also work. Model and knob names are listed in device_map.json.

Patch format

{
  "blocks": {
    "efx": {"model": "T Scream", "knobs": {"drive": 15, "tone": 55, "level": 85}},
    "amp": {"model": "Vivo", "knobs": {"gain": 68, "middle": 68, "treble": 58}},
    "ir":  {"model": "V412"},
    "dly": {"model": "Digital Delay", "knobs": {"e.level": 30, "feedback": 32, "subd": 5}},
    "mod": {"on": false}
  }
}

Selecting a model resets that block's knobs to the model defaults, so set knobs after the model (apply_patch does this in the right order). The files in examples/patches are starting points recreated by ear from recordings. They are not official artist presets.

Limitations

• The device does not report knob changes you make with its own controls. The server re-reads the edit buffer when it needs the current state.
• The signal-chain order cannot be changed through MIDI yet. To get a different chain, start from a preset that already has it (for example, the factory acoustic presets put the IR before the amp).
• Parts of the preset format are still unknown: parts 1–2 of each preset, and the data after the name (probably footswitch and expression assignments). These are preserved untouched when writing.
• Unverified: wah pedal position (CC11), send/return knobs, patch volume, CC79.
• The MG-30 drops MIDI messages sent faster than about 40 ms apart, so the server throttles itself.

How it works

Everything is documented in docs/PROTOCOL.md: the CC map, the SysEx read/write/commit commands, and the 7-bit slot layout of the preset data. Findings for other firmware versions or other NUX units are very welcome.

Development

.venv/bin/pip install -e ".[dev]"
.venv/bin/pytest

The tests run against a fake device and a real preset dump, so no hardware is needed. With MG30_DEBUG_TOOLS=1 the server also exposes debug_monitor (record incoming MIDI), debug_sysex_query, debug_send_cc, debug_send_sysex and debug_probe_cc (find which bits of the preset a CC changes). These tools were used to reverse-engineer the format.

License

MIT, see LICENSE.

NUX, MG-30 and QuickTone are trademarks of their respective owners. Model names used by the device, such as amp and pedal names, refer to the products they emulate and are used here only to identify the models.