GVM DMX Controller: CLI and MCP Server

Control GVM PRO-BD45R 48" RGB LED tube lights over DMX512 from a laptop, with a command-line tool (gvm) and a local MCP server so Claude (or any MCP client) can run the lights: "make the tubes warm white at 40%", "run a slow cyan meteor", "paint a sunset gradient".

• White light 2700–10000 K with green/magenta, solid colours (names, hex, RGB, hue), HSI

• Per-pixel control: each tube is 33 individually addressable pixels

• Gradients and exact per-pixel painting

• Software versions of all six GVM pixel effects (rolling, rainbow, blockgame, pingpong, wave, meteor), plus rig effects across tubes (colour cycle, chase, table ping pong)

• Works with cheap FTDI "Open DMX" USB cables (tested with the DSD TECH SH-RS09B)

• The tubes hold their last look, so static commands set it and exit. Effects stream until stopped.

• Every rig setting (adapter, addresses, modes, pixel layout, orientation) comes from a config file or command-line options / MCP tool parameters

New here? Set each tube's menu first (Settings on each light), then read the setup guide. It covers the wiring, the XLR-to-RJ45 pinout (the most common reason nothing works), install, first tests, connecting Claude, and troubleshooting.

GVM's own documents: the BD45R DMX channel table (PDF) and the BD25R / BD45R user manual (PDF). Cable pinouts: Wiring and pinouts. More under Reference documents.

Settings on each light

Nothing works until each tube's own menu matches the software's patch. On each BD45R, press MODE until the Set up menu appears, press TAB to move between items and + / − to change them:

The software shows the same settings for the config in use, so they can't drift apart:

• gvm setup prints the exact menu values per tube, the wiring chain, the adapter pinout and the terminator. gvm info adds a set on the light: line under each tube.

• The MCP server's rig_info tool includes set_on_light for each tube, and its light_setup_guide tool returns the full checklist, so Claude can walk you through it.

Other layouts (other modes, fewer pixels, more tubes) are in setup §3, including how to work out addresses.

Using more than one tube

With more than one tube, effects can play across the whole rig, not just along each tube: a chase that runs from one tube into the next, colors that travel down a row of tubes, or a ping-pong ball that bounces between two tubes facing each other. For that, the software needs to know which way each tube is mounted. Each tube's pixel order can be flipped with reverse (in gvm.toml, or :reverse in a --patch spec).

You don't have to work this out yourself. Describe your layout to the agent, for example:

"My two tubes face each other across a table. Set them up so effects travel around the table."

It runs a test pattern, asks what you see, and sets reverse for each tube to match.

Related MCP server: elgato-keylight

Contents

• Settings on each light

• How it fits together

• Wiring and pinouts

• Quick start

• CLI reference

• Using the MCP server

• Using with a camera and motion control

• Configuration

• Effects

• Python library

• Development

• Project layout

• Reference documents

How it fits together

 Claude / MCP client ──stdio──▶ gvm mcp ─┐
                                         ├─▶ Controller ─▶ FTDI D2XX ─▶ USB-DMX cable ─▶ XLR→RJ45 ─▶ Tube 1 ─▶ Tube 2 ─▶ terminator
 You ─────────────────────────▶ gvm ... ─┘        │
                                                  └─ universe state file (last values of all 512 channels)

• Open DMX adapter: the SH-RS09B is a bare USB-to-RS485 bridge, so this software generates the DMX signal itself (break, mark-after-break, 512 slots at 250 kbaud, about 25 frames/s).

• The tubes hold their last values when DMX stops, so a static command opens the adapter, sends briefly and closes it again.

• Shared state: the last universe is saved to a state file and restored on the next command, so the CLI and the MCP server can take turns, and changing one tube never resets another.

Wiring and pinouts

Parts

Don't skip the terminator. DMX is a 120 Ω bus. Without a terminator at the far end, the signal reflects back down the cable, and the last tube can flicker, glitch or ignore commands, especially on longer runs. To make one, wire a 120 Ω, ¼ W resistor between pins 1 and 2 of an RJ45 plug (or of a short patch cable cut off near the plug), and plug it into the last tube's DMX OUT. A 3-pin XLR terminator (120 Ω between XLR pins 2 and 3) only works if that end of the chain is XLR.

Adapter warning. Sellers rarely publish pinouts, and many "XLR to RJ45" or "DMX" adapters (audio types, LED-strip controllers) are wired differently. One tested for this project mapped XLR 1/2/3 to RJ45 1/6/7, and the tubes only flickered. SIRS-E lists RJ45 pin 1 Data+ (white/orange), pin 2 Data− (orange) and pins 7/8 ground, matching XLR pins 3/2/1 by wire colour. Event Horizon builds to the pinout you select. Neither has been tested with these tubes, so check any adapter with a meter, or build one from the table below.

Pinouts

Laptop USB ─ USB-DMX cable (XLR) ─ XLR→RJ45 DMX adapter ─▶ Tube 1 DMX IN
                                   Tube 1 DMX OUT ─ Cat5 ─▶ Tube 2 DMX IN ─ Tube 2 DMX OUT ─ 120 Ω terminator

The tubes' DMX jacks are RJ45, so the XLR end of the USB cable needs an adapter, and the adapter must be wired to the DMX-over-Cat5 standard (ANSI/ESTA E1.27-2). Many "XLR to RJ45" adapters (audio types, and some sold for LED-strip controllers) use other pins. With one of those, the tubes flicker or ignore DMX.

RJ45 pins are numbered 1–8 left to right with the gold contacts facing you, the clip at the back and the cable hanging down. The full details are in the setup guide: wiring and pinouts, including how to check an adapter with a multimeter, how to build one, and connector genders. The standard itself is in the ANSI E1.27-2 wiring guide (PDF).

Quick start

1. Wire it up (Wiring and pinouts): USB cable → ESTA XLR-to-RJ45 adapter → tube 1 IN, tube 1 OUT → tube 2 IN, terminator in tube 2 OUT.

2. Set each tube's menu (Settings on each light): CONTROL DMX, DMX MODE CCT&RGB, DMX PIXEL 1, DMX ADDR 1 and 232.

3. Install the software. It needs Python 3.11+ and the FTDI driver, which Windows installs automatically for the cable.

git clone https://github.com/cleemullins/GVM-DMX-Controller---CLI-and-MCP-Server.git gvm
cd gvm
python -m pip install -e .

Check the adapter is seen, and compare the settings the software expects with each tube's menu:

gvm ports

gvm setup

Then try the lights:

gvm white 100 5600

gvm fx all

If gvm isn't found, use python -m gvm instead, or add Python's Scripts folder to PATH (see setup §5).

4. Connect Claude or another assistant: see Using the MCP server.

CLI reference

gvm [rig options] COMMAND [command options]

Targeting: -f/--fixture NAME (repeatable; default all tubes) and -s/--segment N (repeatable; 1–33).

Rig options override the config file. Put them before the command:

gvm --patch "tube1:1:CCT&RGB:1:reverse" --patch "tube2:232:CCT&RGB:1" white 50

gvm --driver serial --device COM3 info

Run gvm --help or gvm COMMAND --help for every option.

Using the MCP server

The MCP server lets Claude, or any other MCP-capable assistant, run the lights in plain language: "set both tubes to 3200 K at 40%", "make tube 2 deep blue", "run a slow cyan meteor", "paint a sunset gradient", "stop the effect". It runs locally over stdio: your MCP client starts gvm mcp as a subprocess on your computer and talks to it over stdin/stdout. No network port is opened, and nothing leaves the machine except what the assistant itself sends.

1. Before you start

1. The lights work from the CLI. Wiring, tube settings and install are done (see Quick start), and gvm white 50 5600 lights both tubes. If the CLI can't drive the lights, the MCP server can't either.

2. Find the Python that has gvm installed. MCP clients often don't share your terminal's PATH, so use the full path to python.exe in client configs. To print it:

   python -c "import sys; print(sys.executable)"

   It looks like C:\Users\<you>\AppData\Local\Python\pythoncore-3.15-64\python.exe.

3. Make the config findable. The client starts the server in a folder of its choosing, so ./gvm.toml may not be found. Either pass --config in the client config (as in the examples below), or put the config in the per-user location that gvm always checks:

   gvm init

   This writes %APPDATA%\gvm\gvm.toml. Edit it to match your tubes, or copy this repo's gvm.toml over it.

4. Check the server starts. This prints nothing and waits for a client; stop it with Ctrl+C. An error here, such as a missing config or a bad patch, is the same one a client would hit.

   python -m gvm mcp

2. Connect it to your assistant

The server is the command python -m gvm [rig options] mcp. Every client below just needs that command and its arguments. Rig options (--config, --patch, --driver, --device) go before mcp.

Claude Code, in this repo. Nothing to do: the repo's .mcp.json declares the gvm-lights server. Open Claude Code in this folder and approve the server when asked. It uses python from your PATH and ./gvm.toml.

Claude Code, in any folder. Register it once for your user (with a per-user config, step 1.3):

claude mcp add --scope user gvm-lights -- python -m gvm mcp

Use the full python.exe path instead of python if it isn't on your PATH, and add --config C:\path\to\gvm.toml before mcp to pin a config.

Claude Desktop. Settings → Developer → Edit Config opens claude_desktop_config.json (%APPDATA%\Claude\ on Windows, ~/Library/Application Support/Claude/ on macOS). Add the server, save, and fully quit and reopen Claude Desktop:

{
  "mcpServers": {
    "gvm-lights": {
      "command": "C:\\Users\\<you>\\AppData\\Local\\Python\\pythoncore-3.15-64\\python.exe",
      "args": ["-m", "gvm", "--config", "C:\\git\\gvm\\gvm.toml", "mcp"]
    }
  }
}

Other MCP clients (VS Code, Cursor, Windsurf, Zed, and others) take the same command and arguments in their own config file. For example, VS Code's .vscode/mcp.json:

{
  "servers": {
    "gvm-lights": {
      "type": "stdio",
      "command": "C:\\path\\to\\python.exe",
      "args": ["-m", "gvm", "--config", "C:\\git\\gvm\\gvm.toml", "mcp"]
    }
  }
}

Any client that supports stdio MCP servers works. The server needs no environment variables or API keys.

Without an assistant. The MCP Inspector lets you call the tools by hand in a browser (needs Node.js):

npx @modelcontextprotocol/inspector python -m gvm mcp

3. Check it's connected

• Claude Code: run /mcp. gvm-lights should show as connected, with its 12 tools.

• Claude Desktop: the tools/connectors menu in the chat box should list gvm-lights.

• Then ask: "What lights do you have?" The assistant should call rig_info and report two tubes with 33 segments each, plus the menu settings each tube needs.

4. Things to ask

Colours can be names (red, amber, teal, …), #rrggbb, r,g,b or hue:DEG[,SAT]. Intensities are 0–100 %. Segments are numbered 1–33 along each tube.

5. How it behaves

• Static tools (set_white, set_color, set_hsi, set_intensity, paint, lights_off) return as soon as the look is set. The tubes keep it after that, even when the server stops.

• Effects run in the background. start_effect returns immediately, and the animation keeps going until stop_effect, another lighting tool, its seconds running out, or the client closing the server. Then the tubes go dark.

• One adapter, one user at a time. A running effect holds the USB-DMX adapter, so stop it before using the gvm CLI or other DMX software, or they report the adapter as busy. Static changes hold it for only a fraction of a second.

• Shared state. The last values of all 512 channels are saved per user, so the MCP server and the CLI can take turns without resetting each other's tubes.

• The patch can change mid-session. If a tube's DMX ADDR, DMX MODE or DMX PIXEL is changed on the light, tell the assistant: it calls configure_rig for that session. Update gvm.toml to make the change permanent.

6. Tools

fixtures takes tube names or numbers (omit for all), and segments takes 1–33 (omit for the whole tube).

7. Troubleshooting the MCP server

Using with a camera and motion control

The lights are one part of a studio. With a camera MCP server (for example, one for a Nikon) and edelkrone's MCP server for sliders and heads, one assistant can light, move and shoot in a single request. Each device keeps its own server: register all three with the same client, and the assistant coordinates them.

{
  "mcpServers": {
    "gvm-lights": { "command": "C:\\path\\to\\python.exe", "args": ["-m", "gvm", "--config", "C:\\git\\gvm\\gvm.toml", "mcp"] },
    "camera":     { "...": "your camera MCP server" },
    "edelkrone":  { "...": "edelkrone's MCP server" }
  }
}

How the lights fit in

• Set the look, then shoot. Static looks (set_white, set_color, paint) stay on the tubes with nothing left running, so they don't change during an exposure.

• Effects run while other things happen. start_effect returns straight away, so the camera can start recording and the slider can move while the tubes animate. End with stop_effect.

• Frame-by-frame work (turnarounds, time-lapse, stop-motion): change the light → move → wait for the motion to settle → capture, repeated. Use static looks between frames, not effects.

• Match white balance. When using white light, set the camera's white balance to the tubes' colour temperature.

• Motion is real hardware. edelkrone's server asks the assistant to read its SDK info and safety rules first. Confirm move ranges before the first run.

Example requests

Rename capabilities to match what your camera server exposes.

Configuration

gvm.toml (this repo's copy is set up for two tubes):

driver = "d2xx"        # "d2xx" (FTDI library, recommended) or "serial"
device = ""            # FTDI serial (from `gvm ports`) or COM port; "" = first adapter
fps = 25

[[fixture]]
name = "tube1"
address = 1            # = the tube's DMX ADDR
mode = "CCT&RGB"       # = DMX MODE: CCT&RGB | CCT&HSI | CCT | RGB | HSI | EFFECT | PIXEL FX
pixel = 1              # = DMX PIXEL: 33 (whole tube) | 11 | 3 | 1 (33 pixels)
reverse = true         # flip pixel order (see "Using more than one tube")

[[fixture]]
name = "tube2"
address = 232
mode = "CCT&RGB"
pixel = 1
reverse = false

Lookup order: --config, $GVM_CONFIG, ./gvm.toml, %APPDATA%\gvm\gvm.toml (~/.config/gvm/gvm.toml on Linux/macOS). See setup §3 for working out addresses for other layouts.

Effects

gvm fx list / the rig_info tool lists them. All take speed 1–10 (5 = normal) and seconds (0 = until stopped). Pixel effects need DMX PIXEL below 33.

gvm fx wave --color red --bg green --wavelength 8 --seconds 20

gvm fx cycle --stagger 10 --seconds 30

Python library

from pathlib import Path
from gvm import Controller, RigConfig
from gvm.animations import Options

ctl = Controller(RigConfig.load(Path("gvm.toml")))
ctl.white(60, 4300)
ctl.color((255, 0, 128), 40, fixtures=["tube2"])
ctl.paint([(255, 0, 0), (0, 0, 255)])
ctl.start("meteor", Options(color=(0, 255, 255), speed=7))   # background thread
ctl.stop()

The lower layers are gvm.dmx.OpenDmx (raw universe output) and gvm.bd45r.BD45R (the tube's channel map). The channel chart is in docs/bd45r-dmx-channels.md.

Development

python -m pip install -e ".[test]"

python -m pytest

The tests don't need hardware. CI runs them on every push (see .github/workflows/tests.yml).

Project layout

Reference documents

License

MIT © 2026 Chris Mullins. GVM and BD45R are trademarks of their owner; this project is not affiliated with or endorsed by GVM.