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

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

MADRIX MCP

MADRIX MCP

Quick start

Configuration

Architecture

Safety profiles

Tools

Transport and safety

Identity and global state

Playback and state reads

Fade and master control

Storage and deck control

Cue list control

Audio and output control

Group control

Timeline control

Global color control

Deck storage-place control

Ticker and BPM control

Layer control (generated families)

Claude Desktop

VS Code / Cursor

Codex

Production safety

Live validation

Development

License

Score

Proud of your score? Add this badge to your README.

MADRIX MCP FAQ

How do I install MADRIX MCP?

Is MADRIX MCP an official MCP server?

Related MCP servers

Related guides