<p align="center"> <img src="assets/banner.svg" alt="MADRIX MCP" width="100%"> </p>

MADRIX MCP

<p align="center"> <a href="https://github.com/drohi-r/madrix-mcp/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-Apache_2.0-orange?style=for-the-badge" alt="License"></a> <img src="https://img.shields.io/badge/Python-3.12%2B-blue?style=for-the-badge" alt="Python 3.12+"> <img src="https://img.shields.io/badge/MCP_Tools-108-00E0A4?style=for-the-badge" alt="108 MCP Tools"> <img src="https://img.shields.io/badge/Tests-67-00E0A4?style=for-the-badge" alt="67 Tests"> </p>

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:

• HttpRemoteControl
• Product 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