NUX MG-30

nux-mg30-mcp

一个 MCP 服务，可让 AI 助手（Claude Desktop 或其他 MCP 客户端）通过 USB MIDI 控制 NUX MG-30 吉他处理器。

用通俗的语言描述你想要的音色（“Children of Bodom 风格的紧实节奏音色”“主音少些毛刺感，多些中频”），助手就会选择模型、调节旋钮，并在设备上保存和命名预设。

非官方项目。 本项目与 NUX / Cherub Technology 无关，也未获得其认可。预设协议是基于固件 5.0.2 逆向分析得出的，其他固件版本可能有所不同。写入预设会覆盖设备上的插槽，因此请先运行 backup_presets。

功能

• 实时编辑： 在任意模块中选择模型（35 个音箱、24 个箱体/IR、15 个过载、14 个调制、8 个延迟、6 个混响等），开关模块，并按名称设置旋钮（gain、middle、1.2k、subd 等）。
• 读取预设： 列出全部 128 个预设及其名称和音箱，解码任意预设（名称、信号链、模型、旋钮值），并读取包含未保存更改的编辑缓冲区。
• 写入预设： 将编辑缓冲区保存到任意插槽并命名，重命名预设，以及通过 JSON 文件备份或还原预设。每次写入后都会读取并验证。
• 音色方案： 从 JSON 音色文件应用完整音色。示例见 examples/patches。

要求

• 通过 USB 连接的 NUX MG-30。设备会显示为符合类标准的 MIDI 端口。
• Python 3.10+。
• MCP 客户端，例如 Claude Desktop。

由于需要直接访问 USB MIDI 端口，服务必须运行在连接 MG-30 的计算机上。开发和测试在 macOS 上完成；通过 python-rtmidi 应该也能在 Linux 和 Windows 上运行，但未经测试。

安装

最简单的方法是使用 uv：uvx 会下载并运行服务，无需手动设置。

Claude Desktop

打开 Settings → Developer → Edit Config 并添加：

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

完全重启 Claude Desktop。工具会显示在 nux-mg30 服务下。如果 Claude 找不到 uvx，请使用其绝对路径（which uvx，通常是 ~/.local/bin/uvx）。

或者，使用 pipx install nux-mg30-mcp 或 pip install nux-mg30-mcp 安装，并设置 "command": "nux-mg30-mcp"。

从源码安装

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

然后在客户端配置中使用 "command": "/absolute/path/to/nux-mg30-mcp/.venv/bin/nux-mg30-mcp"。

可选检查，无需 AI 客户端：先调低音量，再运行 python scripts/midi_check.py。该脚本会将 AMP 模块静音 1.5 秒，然后恢复。

配置

变量	默认值	含义
MG30_PORT	自动（MG-30 / NUX）	MIDI 端口名称的子字符串
MG30_CHANNEL	1	设备上设置的 MIDI 通道
MG30_DATA_DIR	~/.nux-mg30-mcp	存储备份、音色文件和日志的位置
MG30_DEVICE_MAP	内置	自定义 device_map.json 的路径
MG30_DEBUG_TOOLS	关闭	设为 1 后会公开底层研究工具

在 MCP 客户端配置的 "env" 下添加这些变量。

入门步骤

1. 请助手备份所有预设（backup_presets）。
2. 请助手列出预设，查看各预设所在位置。
3. 选择一个空闲或不重要的插槽，并描述想要的音色。例如：“切换到 12C，制作一个 Death《Sound of Perseverance》风格的节奏音色，然后将其保存为‘Chuck Rhythm’。”

工具

工具	功能
connect, list_midi_ports	查找并打开 MG-30
device_state	查看编辑缓冲区中的当前预设、模型、开关状态和旋钮设置
set_model(block, model, on)	按名称或编号选择模型
set_block(block, on)	打开或关闭一个模块
set_knob(block, knob, value)	按标签或索引设置旋钮，范围为 0..100
apply_patch(patch)	一次性设置多个模块的模型、开关状态和旋钮
select_preset(preset)	切换预设（'07A' 或 0..127）
list_presets, preset_info(preset)	读取并解码已存储的预设或编辑缓冲区
save_preset(preset, name)	将编辑缓冲区保存到插槽，并通过回读进行验证
rename_preset(preset, name)	重命名已存储的预设
backup_presets, list_backups, restore_preset	完整备份和单个预设恢复
save_patch_file, list_patch_files, load_patch_file	将音色配置保存为 JSON 文件

模块包括 wah、comp、efx、amp、eq、ng（噪声门）、mod、dly、rvb、ir（箱体模拟）和 sendreturn。也支持 delay、reverb、cab 和 gate 等常见别名。模型和旋钮名称列于 device_map.json。

Patch 格式

{
  "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}
  }
}

选择模型会将该模块的旋钮重置为模型默认值，因此请在选择模型后设置旋钮（apply_patch 会按正确顺序执行）。examples/patches 中的文件是根据录音凭听感重建的起始配置，并非官方艺人预设。

局限

• 设备不会报告通过自身控制器进行的旋钮更改。服务会在需要当前状态时重新读取编辑缓冲区。
• 目前无法通过 MIDI 更改信号链顺序。若要使用不同的信号链，请从已有该信号链的预设开始（例如，出厂原声预设会将 IR 放在 amp 前）。
• 预设格式的部分内容仍不明确：每个预设的第 1–2 部分，以及名称之后的数据（可能是脚踏开关和表情控制器分配）。写入时会原样保留这些内容。
• 尚未验证：哇音踏板位置（CC11）、发送/返回旋钮、Patch 音量、CC79。
• MG-30 会丢弃间隔小于约 40 ms 发送的 MIDI 消息，因此服务会自动降低发送速率。

工作原理

所有内容均记录在 docs/PROTOCOL.md 中：CC 映射、SysEx 读取/写入/提交命令，以及预设数据的 7 位插槽布局。欢迎提供其他固件版本或其他 NUX 设备的相关发现。

开发

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

测试使用模拟设备和真实预设转储运行，因此无需硬件。设置 MG30_DEBUG_TOOLS=1 后，服务还会公开 debug_monitor（记录传入的 MIDI）、debug_sysex_query、debug_send_cc、debug_send_sysex 和 debug_probe_cc（查找 CC 会更改预设中的哪些位）。这些工具曾用于逆向分析该格式。

许可证

MIT，详见 LICENSE。

NUX、MG-30 和 QuickTone 是其各自所有者的商标。设备使用的模型名称（例如 amp 和踏板名称）指代其模拟的产品，在此仅用于标识模型。