Resolume MCP

An MCP server for Resolume Arena and Avenue. Exposes 206 tools covering composition control, playback, Advanced Output management, and show recovery — so AI assistants can operate Resolume via REST, WebSocket, and OSC.

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

What it does

Area	What you get
Composition control	Layers, clips, columns, groups, decks — get snapshots, trigger playback, manage media, batch operations
Advanced Output	Screen and slice management via both REST API and XML inspection. Backup, diff, rename, reroute, warp alignment
Playback & monitoring	Transport control, parameter subscriptions, state polling, show-readiness audits
Effects	Add, remove, move, rename effects across composition, layer, group, and clip scopes
Safety	16 destructive operations gated behind confirm_destructive=True. Atomic XML writes. Crash-resilient polling

Quick start

# Clone and install
git clone https://github.com/drohi-r/resolume-mcp && cd resolume-mcp
uv sync

# Run the server (connects to Resolume on localhost:8080)
uv run python -m resolume_mcp

Make sure Resolume Arena or Avenue is running with the REST API enabled (Preferences → OSC/HTTP → HTTP API).

For remote control:

• use LAN or WireGuard, not the public internet
• set RESOLUME_HOST to the remote machine
• include that host in RESOLUME_ALLOWED_HOSTS

Configuration

The server reads configuration from environment variables. All have sensible defaults for local development.

Variable	Default	Description
RESOLUME_HOST	127.0.0.1	Resolume instance IP
RESOLUME_HTTP_PORT	8080	HTTP API port
RESOLUME_OSC_PORT	7000	OSC listener port
RESOLUME_ALLOWED_HOSTS	127.0.0.1,localhost,::1	Comma-separated allowlist for target hosts. Set * to allow any.
RESOLUME_USE_HTTPS	false	Use HTTPS for API calls (true, yes, 1)
RESOLUME_DOCUMENTS_ROOT	~/Documents/Resolume Arena	Resolume documents path
RESOLUME_ADVANCED_OUTPUT_XML	~/Documents/Resolume Arena/Preferences/AdvancedOutput.xml	Advanced Output XML path
RESOLUME_SLICES_XML	~/Documents/Resolume Arena/Preferences/slices.xml	Slices XML path

Architecture

graph TD
    A["Resolume MCP Server<br/><code>resolume_mcp</code><br/>206 tools · safety gate"] --> B
    A --> C
    A --> D
    B["REST Client<br/>Composition · clips · layers · effects"] --> E
    C["WebSocket Client<br/>Parameter subscriptions · state polling"] --> E
    D["OSC Client<br/>Transport control"] --> E
    E["Resolume Arena / Avenue<br/>HTTP API on port 8080"]

    F["Advanced Output Engine<br/>XML inspection · atomic writes · backup"] -.-> A
    G["Safety Gate<br/>16 destructive ops gated behind confirm"] -.-> A

    style A fill:#1a1a2e,stroke:#9B59FF,color:#fff
    style B fill:#1a1a2e,stroke:#9B59FF,color:#fff
    style C fill:#1a1a2e,stroke:#9B59FF,color:#fff
    style D fill:#1a1a2e,stroke:#9B59FF,color:#fff
    style E fill:#1a1a2e,stroke:#0f3460,color:#fff
    style F fill:#0f3460,stroke:#0f3460,color:#fff
    style G fill:#0f3460,stroke:#0f3460,color:#fff

Loading

Claude Desktop

Add this to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "resolume": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/resolume-mcp", "python", "-m", "resolume_mcp"],
      "env": {
        "RESOLUME_HOST": "127.0.0.1",
        "RESOLUME_HTTP_PORT": "8080",
        "RESOLUME_ALLOWED_HOSTS": "127.0.0.1,localhost,::1"
      }
    }
  }
}

VS Code / Cursor

Add to .vscode/mcp.json in your project:

{
  "servers": {
    "resolume": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/resolume-mcp", "python", "-m", "resolume_mcp"],
      "env": {
        "RESOLUME_HOST": "127.0.0.1",
        "RESOLUME_HTTP_PORT": "8080",
        "RESOLUME_ALLOWED_HOSTS": "127.0.0.1,localhost,::1"
      }
    }
  }
}

Codex

Create a codex.json MCP config file:

{
  "mcpServers": {
    "resolume": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/resolume-mcp", "python", "-m", "resolume_mcp"],
      "env": {
        "RESOLUME_HOST": "127.0.0.1",
        "RESOLUME_HTTP_PORT": "8080",
        "RESOLUME_ALLOWED_HOSTS": "127.0.0.1,localhost,::1"
      }
    }
  }
}

Then run Codex with:

codex --mcp-config codex.json

Skills

The server includes 7 operator skills — structured workflows for common live-show scenarios:

Skill	When to use
playback-prep-and-busking	Preparing Resolume for a live run or operator handoff
advanced-output-setup	Setting up screens, slices, and routing for a show
output-routing-festival	Fast rerouting for festival or guest rig changes
output-warp-alignment	Aligning screen geometry and slice warping
festival-recovery-fast	Recovering a show under time pressure
show-recovery-and-triage	Diagnosing transport, output, or layer issues
deck-control-and-inspection	Managing deck snapshots, audits, and parameters

Safety model

• Read operations (snapshots, audits, parameter gets): always safe, no confirmation needed
• Destructive operations (clear, disconnect, remove): require confirm_destructive=True
• Host allowlisting: only 127.0.0.1, localhost, and ::1 are permitted by default. Add LAN hosts explicitly via RESOLUME_ALLOWED_HOSTS. Set * to allow any host.
• Advanced Output XML writes: atomic (temp file + rename) to prevent corruption
• Polling loops: crash-resilient — return last known state if Resolume becomes unreachable

Development

# Install and sync dependencies
uv sync

# Run tests
uv run python -m pytest -v

License

Apache 2.0