eos-mcp-server

MCP server that lets Claude control an ETC Eos lighting console (Nomad Puck or any Eos-family desk) over OSC — fire and record cues, set channel levels, drive faders, nudge encoders. Built for a test system, not a live rig — see Safety notes below before pointing it at anything with an audience.

How it talks to your rig

Claude → this MCP server → OSC over UDP → Eos (running on your Puck) → sACN → Luminode gateways → DMX → fixtures.

This server never touches DMX/sACN directly — it drives Eos the same way a TouchOSC panel or QLab would, via Eos's OSC command set. Eos remains the single source of truth for the show.

1. Enable OSC on Eos

Setup > System > Show Control > OSC:

• OSC RX: enabled, port 8000 (ETC's recommended default)
• OSC TX: enabled, port 8001, TX IP address = the machine running this server
• Also confirm UDP Strings & OSC is enabled for your network interface under Setup > System > Network > Interface Protocols

The TX IP address is the one people get wrong: it must point at the machine running this server, not at the console. If it doesn't, commands will still work but no feedback or status will ever arrive.

2. Install and build

npm install
npm run build

3. Configure

Environment variables:

Var	Required	Default	Meaning
EOS_HOST	yes	—	IP/hostname of the machine running Eos
EOS_SEND_PORT	no	8000	Eos's OSC RX port
EOS_LISTEN_PORT	no	8001	Local port to receive Eos's OSC TX feedback on
EOS_USER_ID	no	99	OSC user to claim — see below
EOS_VERBOSE	no	off	Set to 1 to log every OSC message to stderr

EOS_USER_ID

Eos gives each OSC user its own command line. This server claims a dedicated virtual user (default 99) so its commands can never merge into a half-typed command on the console operator's line.

• 1–99 — a virtual user with its own command line. Recommended.
• -1 — whoever is currently at the desk. Allowed, but warns at startup: a command sent while the operator is mid-entry can garble theirs.
• 0 — the Eos background user, which has no command line at all. Rejected, because eos_record_cue and eos_send_raw_command would silently do nothing.

4. Run the tests

npm test              # unit + integration tests
npm run test:coverage # with coverage report (80% threshold enforced)

5. Point Claude at it

Add to your MCP client config (e.g. Claude Desktop's claude_desktop_config.json):

{
  "mcpServers": {
    "eos": {
      "command": "node",
      "args": ["/absolute/path/to/eos-mcp-server/dist/index.js"],
      "env": {
        "EOS_HOST": "192.168.1.50"
      }
    }
  }
}

Tools

• eos_fire_cue, eos_go, eos_select_cue — playback
• eos_record_cue — record live state into a cue (overwrites existing cues)
• eos_set_channel_level, eos_select_channel, eos_set_parameter, eos_nudge_wheel — channel/parameter control
• eos_set_fader, eos_configure_fader_bank — OSC fader banks
• eos_fire_macro — run a saved macro
• eos_send_raw_command — escape hatch: send any command-line text
• eos_get_status — read back recent OSC feedback from Eos (active cue, command line echo, etc.)

Diagnostics

Read-only probes for a live console live in tools/diagnostics/ — connectivity, show inventory, and per-channel parameter ranges:

npm run build
EOS_HOST=10.0.0.5 node tools/diagnostics/probe.mjs

What we learned from real hardware

docs/eos-osc-findings.md records behaviour verified against an actual console, including several points where ETC's published OSC documentation is wrong — most importantly that colour arguments are 0–100, not the documented 0–1. Read it before building anything on top of this.

Known issues from live testing

Found while running this against a real Nomad console with a blank/no-cue show file:

• Recording into a cue list that doesn't exist fails. eos_record_cue (and the raw Record Cue <list>/<number> command) errors with Cue List Does Not Exist if the target cue list hasn't been created yet — this includes cue list 1 on a genuinely blank show. Eos does not auto-create the list for you; create it on the console first (or record the very first cue with the bare Record Enter command, which targets cue list 1/cue 1 by default), then subsequent numbered records into that list work normally.

• A failed/unsubmitted command could leak into the next one. (Fixed.) If a command sent via eos_send_raw_command / eos_record_cue errored partway through (e.g. the cue-list issue above), Eos left it sitting open on the shared command line, and the next /eos/newcmd got appended to that leftover text rather than replacing it — producing garbled commands like LIVE: Record Cue 99 /.

  The fix is to stop sharing the command line at all: the server now claims its own OSC user on connect (see EOS_USER_ID), so there is no operator text to collide with. An earlier attempt sent an unverified /eos/key/clear_cmdline before each command; that has been removed in favour of the user-ID approach, which is the documented mechanism.

  Confirmed on hardware: with Chan 5 Thru 8 left un-submitted on the console keypad, a Chan 2 At 25 Enter sent from this server executed correctly and left channels 5–8 and the operator's command line untouched. Reproduce with node tools/diagnostics/user-isolation.mjs.

Safety notes before this touches a live rig

• eos_record_cue and eos_send_raw_command are destructive — they can overwrite show data with no undo prompt over OSC. Fine for a test show file; be deliberate before pointing this at production.
• Both tools require confirm: true to actually execute — without it, they return a preview of what would happen and touch nothing. Calls are also rate-limited (one per few seconds per action) to guard against a runaway loop hammering Record or the command line. See src/services/destructive-guard.ts.
• OSC over UDP has no auth — anyone on the same network segment can send Eos commands. Keep the console's network isolated the way you already do for DMX/sACN.