Resolume Mcp Server

Resolume MCP Server

[](https://www.npmjs.com/package/resolume-mcp-server) [](LICENSE)

Control Resolume Arena/Avenue from AI assistants like Claude using the Model Context Protocol. Trigger clips, fade layers, and pull thumbnails — all through natural language.

Claude  ⇆  resolume-mcp-server  ⇆  http://localhost:8080  ⇆  Resolume Arena
                  (this)                 (Web Server)

Why this server?

Three other Resolume MCP servers exist; this one focuses on a deliberate middle ground:

• Curated tool count — every tool earns its place. Wide-net registries (200+ tools) confuse the model.
• Type-safe end to end — Zod schemas on every input, structured errors with recovery hints the LLM can act on.
• Visual identification — resolume_get_clip_thumbnail returns the actual image, so Claude can pick the right visual when names are ambiguous.
• Destructive-action gating — clear_layer requires explicit confirm: true to prevent accidental wipes during live performance.
• Helpful errors — every error variant carries a hint field telling the LLM what to do next ("Resolume not running — ask the user to launch it and enable the Webserver").
• Push-driven cache (v0.5+) — opt-in CompositionStore consumes Resolume's OSC OUT broadcast (~325 msg/s) so high-frequency reads (clip playhead, BPM, layer opacity) don't pay a REST round-trip.
• Stability tiers (v0.5+) — every tool carries stability: stable | beta | alpha; the RESOLUME_TOOLS_STABILITY env filter lets risk-averse operators hide unstable tools.
• Live-tested — every release verified end-to-end against a real Resolume Arena 7.23. Silent no-ops, wire encoding regressions, and Resolume internals (effect-id re-keying after PUTs, double-broadcast of UI-bound parameters) are documented in docs/v0.5/.

Requirements

• Node.js 20+
• Resolume Arena 7.8+ or Avenue 7.8+ with the Web Server enabled:

1. Open Resolume → Preferences → Web Server
2. Toggle Enable Webserver & REST API on
3. Default port is 8080 (Arena/Avenue) or 8081 (Wire)

Install

npm install -g resolume-mcp-server

Or run without global install via npx:

npx resolume-mcp-server

Configure for Claude

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "resolume": {
      "command": "npx",
      "args": ["-y", "resolume-mcp-server"],
      "env": {
        "RESOLUME_HOST": "127.0.0.1",
        "RESOLUME_PORT": "8080"
      }
    }
  }
}

Claude Code

Add to .mcp.json in your project root:

{
  "mcpServers": {
    "resolume": {
      "command": "npx",
      "args": ["-y", "resolume-mcp-server"]
    }
  }
}

Environment variables

Core (always relevant)

| Variable | Default | Description | |----------|---------|-------------| | RESOLUME_HOST | 127.0.0.1 | Host running Resolume's Web Server | | RESOLUME_PORT | 8080 | Web Server port (8080 Arena/Avenue, 8081 Wire) | | RESOLUME_TIMEOUT_MS | 10000 | Per-request timeout in milliseconds | | RESOLUME_OSC_HOST | 127.0.0.1 | Host running Resolume's OSC ports (same as REST host in most setups) | | RESOLUME_OSC_IN_PORT | 7000 | Resolume's OSC IN port — we send to this | | RESOLUME_OSC_OUT_PORT | 7001 | Resolume's OSC OUT port — we listen on this for queries/subscriptions |

v0.5+ feature flags (all opt-in; defaults reproduce v0.4 behavior bit-for-bit)

| Variable | Values | Default | Description | |----------|--------|---------|-------------| | RESOLUME_CACHE | empty / 0 / 1 / owner / passive / shared | empty (off) | Enables the in-memory CompositionStore cache fed by Resolume's OSC OUT broadcast. 1 / owner binds the OSC OUT port exclusively; passive / shared lets other tools feed the cache via feed(). EADDRINUSE on owner bind auto-degrades to shared mode with a stderr warning. | | RESOLUME_EFFECT_CACHE | 0 / 1 / true / false | 1 (on) | Effect-id cache for setEffectParameter. Single-flight on concurrent calls; layer-wide invalidation on add/remove/wipe/deck-switch. Set to 0 to bisect drift bugs. | | RESOLUME_TOOLS_STABILITY | stable / beta / alpha | beta | Tool tier visibility filter. stable hides beta+alpha tools; alpha exposes everything (operator escape hatches like resolume_cache_refresh). | | RESOLUME_WIPE_CONCURRENCY | 1..16 | 4 | Per-layer parallel POST cap for wipeComposition's /clearclips dispatch. Conservative default keeps Resolume's single-threaded HTTP server happy. |

Tools (v0.5.4 — 39 tools)

All tools are prefixed with resolume_ to avoid collision with other MCP servers. Indices are 1-based to match Resolume's UI. Every tool carries an explicit stability tier; tools/list decorates the description with [BETA] / [ALPHA] prefixes when applicable, and the RESOLUME_TOOLS_STABILITY env var filters what's exposed (default beta shows stable+beta, alpha shows everything, stable hides everything not yet promoted).

Composition

| Tool | What it does | |------|--------------| | resolume_get_composition | Returns version, BPM, layers (with connected clip + bypass state), columns, decks. Call first. | | resolume_get_beat_snap | Current clip beat-snap value + available options (None, 1 Bar, 1/2 Bar, etc.). | | resolume_set_beat_snap | Sets clip beat-snap. Triggered clips wait for the next beat boundary — the core BPM-sync mechanism. | | resolume_get_crossfader / resolume_set_crossfader | Master A/B crossfader. -1 = full Side A, 0 = center, 1 = full Side B. |

Clips

| Tool | What it does | |------|--------------| | resolume_trigger_clip | Plays the clip at {layer, clip} — the most common VJ action. | | resolume_select_clip | Selects without playing. Useful before adjusting parameters. | | resolume_get_clip_thumbnail | Returns the clip's preview image inline so the LLM can see it. | | resolume_get_clip_position (v0.5.1+) | Reads the normalized 0..1 transport position. Cache-first when RESOLUME_CACHE=1 (sub-ms cache hits, no REST round-trip); REST fallback otherwise. Tagged with source: "cache" \| "rest"; cache hits include ageMs. | | resolume_set_clip_play_direction | Forward (>) / pause (||) / reverse ( OSC > OSC Input/Output to be enabled.

| Tool | What it does | |------|--------------| | resolume_osc_send | One-shot OSC message. Power-user escape hatch for paths like /composition/tempocontroller/resync. | | resolume_osc_query | Sends ? query (with optional wildcards) and returns Resolume's echoed values. Fastest way to read many values at once. | | resolume_osc_subscribe | Listens on the OSC OUT port for a duration and collects messages matching a glob pattern. Use /composition/layers/*/clips/*/transport/position for real-time clip-playhead tracking (~325 msg/s). When RESOLUME_CACHE is enabled, transparently multiplexes through the store (no EADDRINUSE). ⚠️ * is segment-bound (OSC 1.0): /a/*/b works, /a/* won't match /a/b/c. Playhead values are normalized 0..1. Pass dedupe: true (v0.5.4+) to collapse Resolume's wire-level double-broadcast on UI-bound parameters (notably /composition/layers/*/position). | | resolume_osc_status | Probes whether Resolume is broadcasting on the configured OSC OUT port. |

Cache (v0.5.1+; gated on RESOLUME_CACHE)

The CompositionStore is an in-memory snapshot fed by Resolume's OSC OUT broadcast (~325 msg/s). When enabled, *Fast read methods on ResolumeClient (and the resolume_get_clip_position tool above) consult it instead of paying a REST round-trip. With the cache off (default), every read goes to REST exactly as in v0.4.

| Tool | What it does | |------|--------------| | resolume_cache_status | Diagnostics: returns { enabled, mode, revision, hydrated, oscLive, msgsReceived, lastOscAt, lastSeedAt, ... }. Read-only. Use to verify the cache is receiving OSC pushes after enabling RESOLUME_CACHE. | | resolume_cache_refresh (alpha — hidden by default) | Operator escape hatch: forces a full REST re-seed. Rate-limited to one call per 500 ms. Set RESOLUME_TOOLS_STABILITY=alpha to expose; intended for recovery (after Resolume restart, or when cache_status shows oscLive=false despite Resolume running). |

Example prompts

> "What's the current state of the composition?"

> "Trigger clip 3 on layer 2."

> "Fade layer 1 down to 0 over a few steps."

> "Show me the thumbnail for layer 1 clip 4 — is that the right one for the chorus?"

> "Clear layer 2." (Claude will ask for confirmation before sending confirm: true.)

Bundled Skill

A Claude Code skill ships in this repo at [skills/resolume-mcp-tester/](./skills/resolume-mcp-tester/SKILL.md). It encodes the operational knowledge accumulated across releases — smoke-test recipes, white-out prevention rules, state-restoration patterns, and agent invocation templates for verifying every tool against a live Resolume Arena.

Install once into your Claude Code skill directory:

# macOS / Linux
mkdir -p ~/.claude/skills
cp -r skills/resolume-mcp-tester ~/.claude/skills/

# Windows (PowerShell)
New-Item -ItemType Directory -Force "$HOME\.claude\skills" | Out-Null
Copy-Item -Recurse -Force skills\resolume-mcp-tester "$HOME\.claude\skills\"

Restart Claude Code, then ask it to "run a comprehensive smoke test of resolume-mcp-server" — it'll load the skill automatically and follow the safety rules. See [skills/README.md](./skills/README.md) for details and the versioning policy.

Roadmap

• ~~v0.2 — Tempo, deck, blend mode, effects (set parameters)~~ ✅ shipped
• ~~v0.3 — Add/remove effects~~ ✅ shipped
• ~~v0.4 — OSC integration (send/query/subscribe/status)~~ ✅ shipped
• ~~v0.5 — CompositionStore cache, effect-id cache, stability tiers, cache-fast read methods, clearclips sub-endpoint, OSC dedupe~~ ✅ shipped (v0.5.0 → v0.5.4)
• v1.0 — npm publish, contract sealed, deprecation policy in effect. Possible additions: resolume_rest whitelisted escape hatch for power users, Advanced Output (screens, slices).

Live-discovered fixes since v0.5.0 are documented in docs/v0.5/:

• [live-test-v0.5.1.md](./docs/v0.5/live-test-v0.5.1.md) — comprehensive smoke test report against Arena 7.23.2
• [osc-duplicate-investigation.md](./docs/v0.5/osc-duplicate-investigation.md) — root cause analysis of Resolume's wire-level double-broadcast (HIGH confidence)
• [review-v0.5.0.md](./docs/v0.5/review-v0.5.0.md) / [review-v0.5.1.md](./docs/v0.5/review-v0.5.1.md) — multi-perspective pre-release reviews

See issues to vote or contribute.

Development

git clone https://github.com/mackatwentytsuru/resolume-mcp-server.git
cd resolume-mcp-server
npm install
npm run build
npm test
npm run test:coverage  # 80%+ thresholds enforced

npm install activates local git hooks (pre-commit runs typecheck + skill-sync drift check in ~3-5s; pre-push adds the full vitest suite). See [CONTRIBUTING.md](./CONTRIBUTING.md#local-git-hooks) for details and bypass instructions.

Project layout:

src/
  resolume/         # REST client, Zod schemas, high-level facade
  tools/            # one tool per file, grouped by domain
  server/           # MCP server registration
  errors/           # tagged-union ResolumeError + HTTP/network mappers
  config.ts         # env-driven config
  index.ts          # stdio entry point

Known Resolume API quirks

• Non-ASCII clip names can break some REST endpoints — keep names ASCII when possible.
• Some WebSocket actions don't ack — handled with optimistic timeouts in upcoming v0.2.
• /product endpoint is recent; older Resolume versions return 404 (handled gracefully).

Comparison with other Resolume MCP servers

| Feature | This server | drohi-r | Ayesy | Tortillaguy | |---------|-------------|---------|-------|-------------| | Tool count | 39 (curated) | 206 | 44 | 2 (search/execute) | | Language | TypeScript | Python | TypeScript | Python | | Schema validation | Zod (strict) | Manual | Zod | None | | Thumbnail as image | ✅ | ❌ | ❌ | ❌ | | Destructive confirmation | ✅ | ✅ | ❌ | ❌ | | Structured errors with hints | ✅ | Partial | Partial | ❌ | | OSC + cache fan-in | ✅ (push-driven, RESOLUME_CACHE=1) | ❌ | ✅ (param cache) | ❌ | | Stability tiers + filter | ✅ (stable/beta/alpha) | ❌ | ❌ | ❌ | | Test coverage | 94%+ statements (483 tests) | — | — | — | | Live-tested against Arena 7.23 | ✅ every release | — | — | — |

Other implementations:

• drohi-r/resolume-mcp — broadest API surface
• Ayesy/resolume-mcp — animation simulation, parameter caching
• Tortillaguy/resolume-mcp — code-execution agent style

License

[MIT](LICENSE)

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: mackatwentytsuru
• Source: mackatwentytsuru/resolume-mcp-server
• License: MIT

Install and usage instructions live in the source repository linked above.