Skip to main content
Glama

MADRIX MCP

An MCP server for MADRIX LED lighting software. Exposes 108 tools covering storage/deck control, layer management, cue lists, timelines, groups, audio, output, global colors, ticker/BPM, and generated layer control families — all via the MADRIX Remote HTTP interface.

Built for live production. Pairs with grandMA2 MCP, Resolume MCP, Companion MCP, and Beyond MCP for full AI-driven show control.

Official MADRIX Remote HTTP docs:

Quick start

git clone https://github.com/drohi-r/madrix-mcp && cd madrix-mcp
uv sync
uv run python -m madrix_mcp

Make sure MADRIX Remote HTTP is enabled and reachable on the configured HTTP port.

For remote control:

  • use LAN or WireGuard, not the public internet

  • set MADRIX_HOST to the MADRIX machine

  • include that host in MADRIX_ALLOWED_HOSTS

Related MCP server: DaVinci Resolve MCP Server

Configuration

Variable

Default

Description

MADRIX_HOST

127.0.0.1

MADRIX instance IP

MADRIX_HTTP_PORT

80

MADRIX Remote HTTP port

MADRIX_REMOTE_PATH

/RemoteCommands/

MADRIX Remote HTTP command path

MADRIX_ALLOWED_HOSTS

127.0.0.1,localhost,::1

Comma-separated allowlist for target hosts. Set * to allow any.

MADRIX_SAFETY_PROFILE

lab

Safety preset: lab, show-safe, or read-only

MADRIX_READ_ONLY

0

Set to 1 for read-only mode

MADRIX_CONFIRM_DESTRUCTIVE

0

Set to 1 to require confirm=true on destructive actions

MADRIX_TIMEOUT_SECONDS

5.0

HTTP timeout

MADRIX_TRANSPORT

stdio

MCP transport (stdio, sse, streamable-http)

Architecture

graph TD
    A["MADRIX MCP Server<br/><code>madrix_mcp</code><br/>108 tools · safety gate"] --> B
    B["HTTP Remote Client<br/>GET/SET commands"] --> C
    C["MADRIX<br/>Remote HTTP on port 80"]

    D["Safety Profiles<br/>lab · show-safe · read-only"] -.-> A
    E["Layer Control<br/>Generated tool families<br/>index + current-layer variants"] -.-> A

    style A fill:#1a1a2e,stroke:#00E0A4,color:#fff
    style B fill:#1a1a2e,stroke:#00E0A4,color:#fff
    style C fill:#1a1a2e,stroke:#0f3460,color:#fff
    style D fill:#0f3460,stroke:#0f3460,color:#fff
    style E fill:#0f3460,stroke:#0f3460,color:#fff

Safety profiles

  • lab — read/write enabled, no extra destructive confirmation

  • show-safe — read/write enabled, destructive operations require confirm=true

  • read-only — blocks all write operations, leaves health/config/read tools available

Tools

Transport and safety

Tool

What it does

get_server_config

Return current MCP server configuration and safety settings

health_check

Probe MADRIX Remote HTTP reachability

get_remote

Raw HTTP GET escape hatch for any MADRIX Remote function

set_remote

Raw HTTP SET escape hatch for any MADRIX Remote function

Identity and global state

Tool

What it does

get_product

Return MADRIX product name

get_version

Return MADRIX version string

get_host_label

Return the MADRIX host label

Playback and state reads

Tool

What it does

get_storage_state

Return current storage deck, place, and position info

get_audio_state

Return audio input level and settings

get_output_state

Return DMX output state

get_cuelist_summary

Return cue list state and entries

get_timeline_summary

Return timeline state and position

get_group_summary

Return group names and values

get_global_colors

Return global color values

get_storage_place_details

Return storage place name and effect info

get_preview_info

Return preview window state

Fade and master control

Tool

What it does

get_fade_type

Return current crossfade type

get_fade_value

Return current crossfade position

set_fade_type

Set the crossfade type

set_fade_value

Set the crossfade position

get_master

Return master brightness

set_master

Set master brightness

get_blackout

Return blackout state

set_blackout

Toggle blackout on/off

Storage and deck control

Tool

What it does

set_storage_place

Switch to a storage place by index

set_deck

Switch active deck (A/B)

set_storage_place_name

Rename a storage place

Cue list control

Tool

What it does

set_cuelist_play

Start/stop cue list playback

set_cuelist_go

Trigger next cue

set_cuelist_back

Go to previous cue

set_cuelist_entry

Jump to a specific cue entry

add_cuelist_entry

Add a new cue list entry

remove_cuelist_entry

Remove a cue list entry

edit_cuelist_entry

Edit an existing cue list entry

Audio and output control

Tool

What it does

set_audio_input

Set audio input source

set_output_enabled

Enable or disable DMX output

Group control

Tool

What it does

set_group_value

Set a group's value by index

set_group_preset

Apply a preset to a group

Timeline control

Tool

What it does

set_timeline_play

Start/stop timeline

set_timeline_position

Seek to a timeline position

Global color control

Tool

What it does

set_global_color

Set a global color by index

Deck storage-place control

Tool

What it does

set_deck_storage_place

Switch storage place on a specific deck

Ticker and BPM control

Tool

What it does

set_bpm

Set the BPM value

set_ticker_enabled

Enable or disable the beat ticker

Layer control (generated families)

Each family provides both index-based and current-layer variants:

Tool

What it does

set_layer_opacity / set_current_layer_opacity

Set layer opacity

set_layer_submaster / set_current_layer_submaster

Set layer submaster

set_layer_blind / set_current_layer_blind

Set layer blind state

set_layer_solo / set_current_layer_solo

Set layer solo state

set_layer_mixmode / set_current_layer_mixmode

Set layer mix mode

set_layer_filter / set_current_layer_filter

Set layer filter

Claude Desktop

{
  "mcpServers": {
    "madrix": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/madrix-mcp", "python", "-m", "madrix_mcp"],
      "env": {
        "MADRIX_HOST": "127.0.0.1",
        "MADRIX_HTTP_PORT": "80",
        "MADRIX_SAFETY_PROFILE": "show-safe"
      }
    }
  }
}

VS Code / Cursor

{
  "servers": {
    "madrix": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/madrix-mcp", "python", "-m", "madrix_mcp"],
      "env": {
        "MADRIX_HOST": "127.0.0.1",
        "MADRIX_HTTP_PORT": "80",
        "MADRIX_SAFETY_PROFILE": "show-safe"
      }
    }
  }
}

Codex

Create a codex.json MCP config file:

{
  "mcpServers": {
    "madrix": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/madrix-mcp", "python", "-m", "madrix_mcp"],
      "env": {
        "MADRIX_HOST": "127.0.0.1",
        "MADRIX_HTTP_PORT": "80",
        "MADRIX_SAFETY_PROFILE": "show-safe"
      }
    }
  }
}

Then run Codex with:

codex --mcp-config codex.json

Production safety

This server is designed for live show environments where accidental writes can disrupt a running LED installation.

  • Host allowlisting — only 127.0.0.1, localhost, and ::1 are permitted by default. Add LAN hosts explicitly via MADRIX_ALLOWED_HOSTS. Set * to allow any host.

  • Read-only mode — set MADRIX_READ_ONLY=1 to block all write operations. Health, config, and read tools remain available.

  • Confirm-destructive gating — set MADRIX_CONFIRM_DESTRUCTIVE=1 to require confirm=true on destructive operations including SetBlackout, SetMaster, storage deck switches, and cue-list play changes.

  • Safety profiles — MADRIX_SAFETY_PROFILE gives you a sane starting point: lab (wide open), show-safe (destructive confirmation), or read-only (no writes).

  • Raw escape hatches — get_remote and set_remote allow any MADRIX Remote HTTP function, but are still gated by the same safety model.

  • Input validation — all tools validate parameters before any HTTP call is made. Invalid inputs return structured JSON errors, never raw exceptions.

  • Error isolation — all tools are wrapped in error handlers. Network failures, validation failures, and unexpected exceptions return {"ok": false, "error": "..."} instead of crashing the MCP session.

Live validation

Validated against a real MADRIX instance on 192.168.20.179:80:

  • health_check, get_product, get_cuelist_summary, get_storage_state

  • get_audio_state, get_output_state, get_timeline_summary, get_group_summary

  • get_storage_place_details, set_master, set_fade_value

  • Generated group write path via SetGroupValue

Development

uv sync
uv run python -m pytest -v   # 67 tests

License

Apache 2.0

Available Tools

108 tools
add_all_occupied_storage_places_to_cuelistD

Inputs: confirm. Returns: result

add_cuelist_cueD

Inputs: confirm. Returns: result

cuelist_backD

Inputs: no named parameters. Returns: result

cuelist_goD

Inputs: no named parameters. Returns: result

cuelist_go_toD

Inputs: index (required). Returns: result

delete_all_cuelist_cuesD

Inputs: confirm. Returns: result

delete_cuelist_cueD

Inputs: index (required), confirm. Returns: result

get_audio_stateD

Inputs: no named parameters. Returns: result

get_blackoutD

Inputs: no named parameters. Returns: result

get_cuelist_summaryD

Inputs: no named parameters. Returns: result

get_fade_timeD

Inputs: no named parameters. Returns: result

get_global_colorD

Inputs: color_id (required). Returns: result

get_group_summaryD

Inputs: group_id (required). Returns: result

get_host_labelD

Inputs: no named parameters. Returns: result

get_masterD

Inputs: no named parameters. Returns: result

get_output_stateD

Inputs: no named parameters. Returns: result

get_preview_infoD

Inputs: no named parameters. Returns: result

get_productD

Inputs: no named parameters. Returns: result

get_server_configD

Inputs: no named parameters. Returns: result

get_storage_place_detailsD

Inputs: place (required), storage (required). Returns: result

get_storage_stateD

Inputs: no named parameters. Returns: result

get_timeline_summaryD

Inputs: no named parameters. Returns: result

get_versionD

Inputs: no named parameters. Returns: result

health_checkD

Inputs: no named parameters. Returns: result

reset_group_values_to_defaultsD

Inputs: confirm. Returns: result

select_layerD

Inputs: deck (required), layer (required). Returns: result

send_http_get_functionD

Inputs: function_name (required), value. Returns: result

send_http_set_functionD

Inputs: value (required), function_name (required), confirm. Returns: result

set_audio_input_faderD

Inputs: value (required). Returns: result

set_audio_input_muteD

Inputs: enabled (required). Returns: result

set_audio_output_faderD

Inputs: value (required). Returns: result

set_audio_output_muteD

Inputs: enabled (required). Returns: result

set_auto_gain_inputD

Inputs: enabled (required). Returns: result

set_blackoutD

Inputs: enabled (required), confirm. Returns: result

set_bpmD

Inputs: value (required). Returns: result

set_cuelist_dateD

Inputs: cue_index (required), date_value (required). Returns: result

set_cuelist_durationD

Inputs: duration (required), cue_index (required). Returns: result

set_cuelist_fade_timeD

Inputs: seconds (required), cue_index (required). Returns: result

set_cuelist_fade_typeD

Inputs: cue_index (required), fade_type (required). Returns: result

set_cuelist_follow_cueD

Inputs: cue_index (required), follow_cue (required). Returns: result

set_cuelist_group_presetD

Inputs: preset (required), cue_index (required). Returns: result

set_cuelist_playback_modeD

Inputs: mode (required). Returns: result

set_cuelist_selectD

Inputs: index (required). Returns: result

set_cuelist_storageD

Inputs: storage (required), cue_index (required). Returns: result

set_cuelist_storage_placeD

Inputs: place (required), cue_index (required). Returns: result

set_cuelist_timecodeD

Inputs: timecode (required), cue_index (required). Returns: result

set_cuelist_timecode_sourceD

Inputs: source (required). Returns: result

set_current_layer_blindC

Set blind for the current layer on deck A or B.

Inputs: deck (required), enabled (required). Returns: result

set_current_layer_filterC

Set value for the current layer on deck A or B.

Inputs: deck (required), value (required). Returns: result

set_current_layer_mixmodeC

Set value for the current layer on deck A or B.

Inputs: deck (required), value (required). Returns: result

set_current_layer_opacityC

Set value for the current layer on deck A or B.

Inputs: deck (required), value (required). Returns: result

set_current_layer_soloC

Set solo for the current layer on deck A or B.

Inputs: deck (required), enabled (required). Returns: result

set_current_layer_submasterC

Set value for the current layer on deck A or B.

Inputs: deck (required), value (required). Returns: result

set_deck_filterD

Set value on deck A or B.

Inputs: deck (required), value (required). Returns: result

set_deck_submasterC

Set value on deck A or B.

Inputs: deck (required), value (required). Returns: result

set_fade_timeD

Inputs: seconds (required). Returns: result

set_fade_typeD

Inputs: name (required). Returns: result

set_fade_valueD

Inputs: value (required). Returns: result

set_global_colorD

Inputs: color_id (required), component_spec (required). Returns: result

set_global_color_channelD

Inputs: value (required), channel (required), color_id (required). Returns: result

set_group_fade_timeD

Inputs: seconds (required). Returns: result

set_group_flash_modeD

Inputs: enabled (required), group_id (required). Returns: result

set_group_presetD

Inputs: index (required). Returns: result

set_group_preset_with_fadeD

Inputs: index (required). Returns: result

set_group_valueD

Inputs: value (required), group_id (required). Returns: result

set_layer_blindC

Set blind for a specific layer on deck A or B.

Inputs: deck (required), layer (required), enabled (required). Returns: result

set_layer_filterC

Set value for a specific layer on deck A or B.

Inputs: deck (required), layer (required), value (required). Returns: result

set_layer_mixmodeC

Set value for a specific layer on deck A or B.

Inputs: deck (required), layer (required), value (required). Returns: result

set_layer_opacityC

Set value for a specific layer on deck A or B.

Inputs: deck (required), layer (required), value (required). Returns: result

set_layer_soloC

Set solo for a specific layer on deck A or B.

Inputs: deck (required), layer (required), enabled (required). Returns: result

set_layer_submasterC

Set value for a specific layer on deck A or B.

Inputs: deck (required), layer (required), value (required). Returns: result

set_masterD

Inputs: level (required), confirm. Returns: result

set_output_filterD

Inputs: level (required). Returns: result

set_output_filter_colorD

Inputs: red (required), blue (required), green (required), white. Returns: result

set_output_freezeD

Inputs: enabled (required). Returns: result

set_output_strobeD

Inputs: enabled (required). Returns: result

set_output_strobe_colorD

Inputs: red (required), blue (required), green (required), white. Returns: result

set_output_strobe_valueD

Inputs: value (required). Returns: result

set_storageD

Inputs: index (required), confirm. Returns: result

set_storage_deck_aD

Inputs: index (required), confirm. Returns: result

set_storage_deck_bD

Inputs: index (required), confirm. Returns: result

set_storage_place_filterD

Set value on deck A or B.

Inputs: deck (required), value (required). Returns: result

set_storage_place_pitchD

Set value on deck A or B.

Inputs: deck (required), value (required). Returns: result

set_storage_place_submasterC

Set value on deck A or B.

Inputs: deck (required), value (required). Returns: result

set_storage_speed_deck_aD

Inputs: value (required). Returns: result

set_storage_speed_deck_bD

Inputs: value (required). Returns: result

set_storage_without_fadeD

Inputs: index (required), confirm. Returns: result

set_storage_without_fade_deck_aD

Inputs: index (required), confirm. Returns: result

set_storage_without_fade_deck_bD

Inputs: index (required), confirm. Returns: result

set_text_tickerD

Inputs: text (required). Returns: result

set_text_ticker_layerD

Inputs: deck (required), text (required), layer (required). Returns: result

set_timelines_playback_stateD

Inputs: state (required). Returns: result

set_timelines_selectD

Inputs: index (required). Returns: result

start_cuelistD

Inputs: confirm. Returns: result

stop_cuelistD

Inputs: confirm. Returns: result

toggle_audio_input_muteD

Inputs: no named parameters. Returns: result

toggle_audio_output_muteD

Inputs: no named parameters. Returns: result

toggle_auto_gain_inputD

Inputs: no named parameters. Returns: result

toggle_blackoutD

Inputs: confirm. Returns: result

toggle_cuelist_playD

Inputs: confirm. Returns: result

toggle_output_freezeD

Inputs: no named parameters. Returns: result

toggle_output_strobeD

Inputs: no named parameters. Returns: result

toggle_storage_speed_pause_deck_aD

Inputs: no named parameters. Returns: result

toggle_storage_speed_pause_deck_bD

Inputs: no named parameters. Returns: result

trigger_fade_autoD

Inputs: no named parameters. Returns: result

trigger_fade_to_centerD

Inputs: no named parameters. Returns: result

trigger_fade_to_deck_aD

Inputs: no named parameters. Returns: result

trigger_fade_to_deck_bD

Inputs: no named parameters. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    D1.5/5.0

    Scored across 108 tools

    Disambiguation2/5

    Many tools have overlapping purposes (e.g., set_current_layer_filter vs set_layer_filter, multiple set storage tools) and lack clear distinctions, making it difficult for an agent to select the correct one.

    Naming Consistency3/5

    Uses snake_case consistently, but verbs vary (get, set, toggle, trigger, add, delete) and some tools like 'select_layer' or 'health_check' break the verb_noun pattern, causing mild inconsistency.

    Tool Count2/5

    With 108 tools, the surface is excessively large for a typical MCP server. While lighting control may require many operations, this count makes the server unwieldy and hard to navigate.

    Completeness3/5

    Covers many aspects like cuelists, groups, layers, audio, and storage, but lacks lifecycle operations such as creating or deleting groups, and some updates are missing, leaving notable gaps.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      C
      maintenance
      An MCP server that lets AI assistants control grandMA2 lighting consoles via Telnet, exposing 41 high-level tools for cue management, fixture control, preset management, executor control, macro editing, appearance assignment, bulk operations, console state queries, show file management, read-back verification, and music show workflows.
      100
      20
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to control DaVinci Resolve Studio through the official Scripting API, with full API coverage plus workflow helpers for editing, grading, Fusion, Fairlight, and project lifecycle tasks. Includes a compound tool mode for low context usage, a granular 341-tool mode, a local control panel, and an optional advanced offline server for working with Resolve project files.
      11,225 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI-driven control of Art-Net/sACN DMX lighting, including scenes, effects, groups, safety rules, MIDI/OSC, and Ableton Live integration through a unified command layer.
      1
      MIT