<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

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

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)

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

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