<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](https://www.madrix.com/) 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](https://github.com/drohi-r/grandma2-mcp), [Resolume MCP](https://github.com/drohi-r/resolume-mcp), [Companion MCP](https://github.com/drohi-r/companion-mcp), and [Beyond MCP](https://github.com/drohi-r/beyond-mcp) for full AI-driven show control.

Official MADRIX Remote HTTP docs:
- [HttpRemoteControl](https://help.madrix.com/m5/httpremote/HttpRemoteControl.html)
- [Product docs](https://help.madrix.com/m5/html/madrix/hidd_remote_http.html)

## Quick start

```bash
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

```mermaid
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

```json
{
  "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

```json
{
  "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:

```json
{
  "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:

```bash
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

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

## License

[Apache 2.0](LICENSE)