CueScope

CueScope is a read-first MCP server that gives AI assistants safe production intelligence for workflows compatible with vMix.

This server connects AI assistants to vMix state, curated production knowledge, and reviewable automation planning. By default it does not switch inputs, run scripts, start streams, change audio, or mutate vMix. It reads first, explains what it sees, and helps you decide what to do next.

Package name: @greenhouselabs/cuescope-mcp

Product Promise

Use CueScope as a read-first production advisor:

You: "Explain my current preset and call out anything risky before the show."

Assistant: [reads vMix state]
           [identifies program, preview, inputs, title fields, overlays, and audio routing]
           [summarizes likely production roles]
           [flags risks and suggests review steps]

The preserved control tools are still available for advanced users, but the default experience is advisory, state-aware, and review-first.

For a first hands-on walkthrough, use DEMO.md. If you used the old control-first prototype, start with MIGRATION.md.

What It Does

| Capability | Default Behavior | |------------|------------------| | Preset analysis | Explains current inputs, roles, active/preview state, overlays, and likely risks | | Input lookup | Finds inputs by number, key, name, type, or fuzzy title matching | | Input inspection | Answers current input questions from live state first, including visible fields and production role hints | | Audio diagnosis | Reviews buses, mute state, solo state, vMix Call patterns, and mix-minus risks | | Troubleshooting guidance | Translates pasted errors and explicit log files/excerpts into likely causes, confidence, and safe next checks | | Script generation | Produces reviewable VB.NET artifacts using actual input references and title fields | | Script validation | Checks VB.NET safety rules, syntax patterns, loop sleeps, and state references | | API planning | Produces ordered vMix function-call plans without calling vMix | | XML comparison | Compares before/after vMix XML snapshots and explains changed production state | | Knowledge resources | Exposes curated vMix API, scripting, audio, production, troubleshooting, forum-pattern, and example notes | | Control Mode | Opt-in access to preserved live-control tools, with highest-impact tools behind a second flag |

Saved .vmix files are explicit evidence. CueScope uses live vMix state first for current show questions, and asks for a .vmix path on the machine running CueScope only when saved-only details are needed, such as stored scripts, input triggers, title countdown/data-source setup, or saved-vs-live drift. Raw XML content is a fallback when a server-visible path is unavailable; chat-uploaded attachments may not be readable by the MCP server.

Quick Start

Prerequisites

• Node.js 20+
• vMix running with Web Controller enabled in Settings > Web Controller
• An MCP-compatible client such as Claude Desktop, Cursor, or Claude CLI

One-Line MCP Setup

The package is published to npm, and no global install is required. Let your MCP client launch the package with npx.

Claude Code CLI:

claude mcp add cuescope -- npx -y @greenhouselabs/cuescope-mcp

Codex CLI:

codex mcp add cuescope -- npx -y @greenhouselabs/cuescope-mcp

With vMix running on another trusted machine:

claude mcp add cuescope -e VMIX_HOST=192.168.1.100 -- npx -y @greenhouselabs/cuescope-mcp
codex mcp add cuescope --env VMIX_HOST=192.168.1.100 -- npx -y @greenhouselabs/cuescope-mcp

For guided desktop setup and first-run smoke tests, see docs/DESKTOP-INSTALL.md. For more setup variants, see docs/MCP-SETUP.md.

Install From Source

Use this while developing or testing an unpublished checkout.

git clone https://github.com/greenhouselabs/cuescope-mcp.git
cd cuescope-mcp
npm install
npm run build

npm Install

npm install -g @greenhouselabs/cuescope-mcp

Global install is optional. The recommended MCP setup above uses npx.

Client Configuration

Most MCP clients accept this JSON shape:

{
  "mcpServers": {
    "cuescope": {
      "command": "npx",
      "args": ["-y", "@greenhouselabs/cuescope-mcp"],
      "env": {
        "VMIX_HOST": "localhost",
        "VMIX_HTTP_PORT": "8088",
        "VMIX_TCP_PORT": "8099"
      }
    }
  }
}

Do not set VMIX_CONTROL_MODE for the default Review Mode experience.

Windows note (vMix is Windows-only, so this affects most users): Claude Desktop on Windows often cannot spawn npx directly and fails with spawn npx ENOENT. Launch it through cmd instead:

{
  "mcpServers": {
    "cuescope": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@greenhouselabs/cuescope-mcp"]
    }
  }
}

If the client still cannot find Node, run where node in a terminal to get the absolute path, then use that full path as the command (pointing args at the package's compiled entry point for a source checkout).

For a source checkout, point the client at the compiled entry point instead:

{
  "mcpServers": {
    "cuescope": {
      "command": "node",
      "args": ["/path/to/cuescope-mcp/build/index.js"],
      "env": {
        "VMIX_HOST": "localhost",
        "VMIX_HTTP_PORT": "8088",
        "VMIX_TCP_PORT": "8099"
      }
    }
  }
}

Claude Code CLI

claude mcp add cuescope -- npx -y @greenhouselabs/cuescope-mcp

Control Mode:

claude mcp add cuescope-control -e VMIX_CONTROL_MODE=true -- npx -y @greenhouselabs/cuescope-mcp

High-Impact Control:

claude mcp add cuescope-high-impact -e VMIX_CONTROL_MODE=true -e VMIX_HIGH_IMPACT=true -- npx -y @greenhouselabs/cuescope-mcp

Codex CLI

codex mcp add cuescope -- npx -y @greenhouselabs/cuescope-mcp

Control Mode:

codex mcp add cuescope-control --env VMIX_CONTROL_MODE=true -- npx -y @greenhouselabs/cuescope-mcp

High-Impact Control:

codex mcp add cuescope-high-impact --env VMIX_CONTROL_MODE=true --env VMIX_HIGH_IMPACT=true -- npx -y @greenhouselabs/cuescope-mcp

Claude Desktop

Use the JSON configuration above in claude_desktop_config.json. The file lives at:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Create the file if it does not exist, then fully quit and reopen Claude Desktop after editing it. On Windows, prefer the cmd /c npx launch shape shown in the Windows note above.

Multiple vMix Instances

To advise on more than one vMix machine (for example a main and a backup mixer), register the server twice under different names with different VMIX_HOST values:

{
  "mcpServers": {
    "vmix-main": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@greenhouselabs/cuescope-mcp"],
      "env": { "VMIX_HOST": "192.168.1.10" }
    },
    "vmix-backup": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@greenhouselabs/cuescope-mcp"],
      "env": { "VMIX_HOST": "192.168.1.11" }
    }
  }
}

Each entry runs its own server process with its own connection, mode flags, and tool surface, and the assistant can address them by name.

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | VMIX_HOST | localhost | vMix hostname or IP address | | VMIX_HTTP_PORT | 8088 | HTTP API port | | VMIX_TCP_PORT | 8099 | TCP API port | | TCP_ENABLED | true | Enable TCP tally subscriptions | | TCP_RECONNECT_DELAY | 5000 | Delay between TCP reconnect attempts in ms | | TCP_MAX_RECONNECTS | 10 | Maximum TCP reconnect attempts | | TCP_CONNECT_TIMEOUT | 10000 | TCP connection timeout in ms | | VMIX_CONTROL_MODE | false | Expose safer live-control tools when set to true | | VMIX_HIGH_IMPACT | false | Expose high-impact control tools when VMIX_CONTROL_MODE=true is also set | | STATE_CACHE_TTL | 100 | Parsed vMix state cache TTL in ms | | SKILLS_PATH | (bundled) | Override the bundled skill-guidance directory | | VMIX_USER_SKILLS_PATH | (none) | Directory of your own skills (<name>/SKILL.md), merged with the bundled ones | | VMIX_PRESET_ROOT | (none) | Optional directory that confines preset-file reads; when set, .vmix files outside it are rejected | | LOG_LEVEL | info | debug, info, warn, or error |

A commented .env.example in the repository documents every variable with its default. Boolean variables use canonical true/false values.

Modes And Safety

Review Mode is the default. It exposes read-only tools that return analysis, validation results, scripts, API plans, assumptions, risk notes, and review checklists. Review Mode does not execute scripts, call vMix shortcut functions, save presets, start streams, start recordings, or perform batch commands.

Control Mode is explicit:

VMIX_CONTROL_MODE=true

Use Control Mode when you intentionally want direct vMix control tools to appear in the MCP client. The highest-impact tools require a second opt-in:

VMIX_CONTROL_MODE=true
VMIX_HIGH_IMPACT=true

High-Impact Control exposes tools for scripts, batch commands, recording, streaming, snapshots, preset open/save, destructive input management, output routing, show-building, and replay recording. Test these workflows on a rehearsal preset before using them during a live show.

Security Notes

Run vMix Web Controller only on trusted machines and networks. This MCP server talks to the vMix HTTP API, which is normally available at http://localhost:8088/api/; exposing that API to the public internet can expose live production control.

Review Mode is the public-safe default. Control Mode and High-Impact Control are explicit opt-ins for users who understand that the assistant can affect a live production. vMix Call join URLs and passwords are treated as sensitive; tools do not return generated call links unless the caller explicitly requests that behavior.

This project is an independent source-available integration for vMix, published by Greenhouse Ventures LLC under the Greenhouse Labs brand. It is not open source, and use is governed by the CueScope Source-Available License. It is not affiliated with, endorsed by, or sponsored by vMix or StudioCoast Pty Ltd. vMix is a trademark of its respective owner.

Review Mode Tools

These tools are visible by default.

| Tool | Purpose | |------|---------| | vmix_show_review | Natural-language show review for "check my show" / "am I ready": combines live state, audio, output readiness, preflight, checklist, and optional saved-preset audio/audit context | | vmix_analyze_preset | Summarize the current live preset, production shape, risks, output readiness, and preflight checks | | vmix_generate_show_checklist | Generate a reviewable rehearsal, go-live, recovery, or end-show operator handoff | | vmix_find_input | Find matching inputs by name, number, key, type, or role clues | | vmix_explain_input | Explain one input's state, fields, audio, and likely production role | | vmix_diagnose_audio | Review audio routing, mute/solo state, buses, call audio, and mix-minus risks | | vmix_diagnose_outputs | Review recording, streaming, external output, video path, audio path, output-like helper inputs, and destination blind spots | | vmix_diagnose_logs | Diagnose pasted vMix/MCP/device log text or one explicit log file with redaction, confidence, and safe next checks | | vmix_generate_script | Generate a preflight-aware reviewable VB.NET script artifact without executing it | | vmix_validate_script | Validate VB.NET script text against vMix scripting rules and known state | | vmix_generate_api_sequence | Generate a preflight-aware ordered vMix API command plan without calling vMix | | vmix_compare_xml_snapshots | Compare two vMix XML snapshots and explain meaningful changes | | vmix_read_preset_file | Read-only inventory of a saved .vmix preset file: compact summary by default; detailMode="full" includes full scripts/triggers (read-only; as last saved) | | vmix_explain_preset_scripts | Plain-language review and risk flags for VB.NET scripts stored in a saved .vmix preset, validated against live state (read-only; as last saved) | | vmix_audit_preset_file | Cross-reference a saved .vmix preset against live vMix state: flags triggers calling missing scripts, triggers targeting absent inputs, saved-vs-live drift, and with targetInput summarizes one input's own triggers plus inbound trigger/script references (read-only; as last saved) | | vmix_preflight | Go-live readiness report: checks program, preview, audio, fade-to-black, overlays, and input roles against heuristic rules and returns a prioritized verdict (ready/caution/not-ready); optionally cross-references a saved .vmix preset (read-only) | | vmix_connection_test | Test connectivity to vMix and diagnose connection problems |

Note: vmix_analyze_preset analyzes live vMix state from the running /api/ endpoint. The vmix_read_preset_file, vmix_explain_preset_scripts, and vmix_audit_preset_file tools read a saved file on disk and reflect the preset as last saved, which may differ from what vMix is currently running.

For single-input saved-preset questions, use targeted summaries before full script dumps: vmix_read_preset_file summary mode for title countdown/data-source bindings, and vmix_audit_preset_file with targetInput for attached triggers, inbound trigger references, and scripts that reference the input. Use detailMode="full" or vmix_explain_preset_scripts when the user asks for exact script bodies, validation, or rewrite guidance.

Control Mode Tools

When VMIX_CONTROL_MODE=true, the server exposes the safer preserved live-control surface. When VMIX_HIGH_IMPACT=true is also set, it exposes the highest-impact tools too.

| Domain | Examples | Gate | |--------|----------|------| | Switching | Cut, fade, transitions, stingers, preview, fade to black | Control Mode | | Audio | Volume, mute, bus assignment | Control Mode | | Graphics | Title text, title images, countdowns, animations | Control Mode | | Overlays | Overlay in, out, and off | Control Mode | | Playback and live adjustments | Playback, layers, browser, vMix Call, PTZ, playlists, color correction, effects, datasource, most replay playback | Control Mode | | Recording and streaming | Record, stream, snapshot, replay recording | High-Impact Control | | Inputs and outputs | Add/remove/rename/reset inputs, output routing, fullscreen, external output | High-Impact Control | | Scripting | Run, stop, save, and legacy script generation tools | High-Impact Control | | Batch, presets, and show-building | Multi-command batches, preset open/save/last, build show, add participant, create multiview | High-Impact Control |

Control Mode keeps the original control prototype salvageable without making live mutation the default product.

Resources

| URI | Description | |-----|-------------| | vmix://server/version | Server version, feature, and build metadata | | vmix://server/status | Active mode, safety boundary, tool counts, and vMix connection config | | vmix://state/summary | Parsed current state summary | | vmix://state/live | Compact live-state view for active, preview, mixes, overlays, audio, and playback | | vmix://state/relationships | Normalized relationships across inputs, overlays, mixes, audio, and titles | | vmix://state/full | Complete raw vMix XML state. Prefer vmix://state/summary for routine checks; the full state can be very large on big productions | | vmix://inputs | All inputs with parsed properties | | vmix://inputs/fields | Title text and image fields across inputs | | vmix://audio | Audio levels, mute states, buses, and solo data | | vmix://script/context | State-aware context for script generation | | vmix://skills | Available vMix skill guidance | | vmix://copilot/context | Higher-level setup analysis for advisory workflows | | vmix://tally | Real-time on-air tally (program/preview per input) from the TCP subscription | | vmix://docs/index | Generated index of curated docs resources and source files | | vmix://docs/mcp-capabilities | MCP knowledge scope, confidence rules, blind spots, and professional-readiness roadmap | | vmix://docs/api | Curated API and shortcut-function notes | | vmix://docs/scripting | Curated VB.NET scripting guidance | | vmix://docs/audio-routing | Curated audio bus and mix-minus guidance | | vmix://docs/production-patterns | Curated production workflow and safe troubleshooting patterns | | vmix://docs/forum-patterns | Curated forum-pattern digests | | vmix://docs/examples | Review-first preset, XML snapshot, routing, and script examples |

Prompts

The server ships reusable MCP prompts that mirror the documented Review Mode workflows. They are available in every mode and only reference read-only tools and resources.

| Prompt | Arguments | Purpose | |--------|-----------|---------| | show-review | path, intent (optional) | Run vmix_show_review for a natural-language production review with output readiness and optional saved-preset context | | preflight-check | none | Run vmix_preflight and summarize go-live readiness with a prioritized verdict | | diagnose-audio | input (optional) | Diagnose audio routing, mutes, mix-minus, and feedback risks; optionally focus on one input | | output-readiness | focus (optional) | Run vmix_diagnose_outputs for recording/streaming/external readiness and destination checks | | explain-my-setup | none | Read the live state summary and relationships and explain the production like a show runbook | | audit-preset | path | Audit a saved .vmix preset file against live state and flag drift and risky triggers | | go-live-checklist | phase (optional) | Generate a reviewable rehearsal, go-live, recovery, or end-show checklist from live state |

Example Requests

"Explain my preset like I am preparing for a show."
"Check my show and tell me if anything needs review before we go live."
"Check whether my recording, streaming, and external outputs are ready."
"Find anything that looks risky in my current vMix setup."
"Diagnose my audio routing and call out mix-minus problems."
"Explain this Blackmagic/vMix error and give me safe next checks."
"Generate a safe script to rotate my camera inputs every 10 seconds."
"Validate this vMix VB.NET script before I paste it into vMix."
"Build a reviewable API sequence for showing a lower third."
"Compare these before and after XML snapshots and explain what changed."

Troubleshooting

vMix state cannot be read / tools return connection errors:

• Confirm the vMix Web Controller is enabled: in vMix, open Settings > Web Controller and tick Enabled. The default port is 8088.
• Verify it from a browser on the vMix machine: open http://localhost:8088/api/ - you should see XML. If you do not, the MCP server cannot read state either.
• Check that VMIX_HOST and VMIX_HTTP_PORT in your MCP config match the actual vMix machine and Web Controller port.
• Confirm vMix itself is running; the Web Controller only responds while vMix is open.
• Run the vmix_connection_test tool from your assistant ("Test the vMix connection and diagnose any problems") for a step-by-step diagnosis.

vMix runs on a different machine (VMIX_HOST is remote):

• On the vMix machine, allow inbound TCP port 8088 (and optionally 8099 for tally) through Windows Firewall, scoped to your trusted production network only.
• Verify reachability from the MCP host first, then keep the Web Controller off the public internet - it is unauthenticated.

TCP tally (port 8099) fails but HTTP state works:

• The TCP connection is optional. The server runs HTTP-only without it; only the real-time vmix://tally resource is affected.
• Confirm VMIX_TCP_PORT matches vMix's TCP API port, or set TCP_ENABLED=false to silence reconnect attempts.

The MCP client cannot start the server:

• On Windows, use the cmd /c npx launch shape shown in the Windows note under Client Configuration; a bare "command": "npx" often fails with spawn npx ENOENT.
• Confirm Node.js 20+ is on the PATH the client uses (node --version, and where node for the absolute path).
• Fully restart the MCP client after any config change so the server relaunches with the new environment.

Where to find logs:

• The MCP server logs to stderr, which your MCP client captures.
• Claude Desktop writes MCP logs to %APPDATA%\Claude\logs on Windows (~/Library/Logs/Claude on macOS); look for the mcp-server-cuescope log file.
• You can paste a redacted error/log excerpt into your assistant, or ask it to use vmix_diagnose_logs on one explicit .log, .txt, .json, .ndjson, .xml, .err, .stderr, or .stdout file path.
• vmix_diagnose_logs does not scan folders, does not execute fixes, and redacts secrets, vMix Call links, stream URLs, private IPs, and local paths before returning excerpts.
• For state-aware troubleshooting, pair log diagnosis with vmix_connection_test, vmix_preflight, vmix_analyze_preset, vmix_diagnose_audio, or saved-preset tools only when those facts can confirm or challenge the log hypothesis.

Demo And Migration

• DEMO.md walks through the first Review Mode demo: status, preset analysis, audio diagnosis, script generation, script validation, API planning, and XML comparison.
• MIGRATION.md explains how old control-first workflows map to Review Mode, Control Mode, and High-Impact Control.

Claude Skills

The skills/ directory contains compact vMix guidance for assistants. The skills are being reframed around Review Mode first: inspect state, reason from actual inputs, generate reviewable artifacts, and only use control tools when the user has explicitly enabled Control Mode or High-Impact Control.

skills/
|-- vmix-basics/        # Switching, transitions, and production-state basics
|-- vmix-audio/         # Mixing, buses, ducking, calls, and mix-minus checks
|-- vmix-graphics/      # Titles, lower thirds, fields, and GT workflows
|-- vmix-overlays/      # Overlay channels, PIP, and stinger guidance
|-- vmix-scripting/     # VB.NET generation and validation
|-- vmix-replay/        # Instant replay workflows
|-- vmix-show-building/ # Complete show setup and review
|-- vmix-streaming/     # Recording, streaming, and external output safety
`-- vmix-troubleshooting/ # Error, log, device, and hardware diagnosis

Architecture

MCP Client (Claude, Cursor, CLI)
    |
    | MCP Protocol over stdio
    v
CueScope
    |
    |-- src/tools/       # Review tools by default, control tools by opt-in flag
    |-- src/resources/   # 21 MCP resources for state, docs, skills, and status
    |-- src/clients/     # vMix HTTP and TCP clients
    |-- src/state/       # XML parser, cache, and normalized relationships
    |-- src/validation/  # VB.NET and API validation helpers
    |-- knowledge/       # Curated production knowledge and examples
    `-- skills/          # Assistant guidance
    |
    v
vMix Instance
    |-- HTTP 8088: XML state and shortcut functions
    `-- TCP 8099: tally and activator subscriptions

Development

npm install
npm run build
npm test
npm run lint
npm run dev
npm run inspector

Recommended release verification:

npm run build
npm run typecheck
npm run lint
npm test
npm audit --audit-level=moderate
node scripts/validate-api-calls.mjs
npm pack --dry-run

MCP Inspector

npm run inspector launches the MCP Inspector against the local build and opens it in your browser. What you should see:

1. The Inspector connects over stdio and the server reports itself as cuescope-mcp with the current version.
2. The Tools tab lists the Review tools only (no control tools) unless you set the control flags in the environment.
3. The Resources tab lists the vmix:// URIs from the table above; reading vmix://server/status should show mode review.
4. With vMix running and the Web Controller enabled, reading vmix://state/summary returns your live preset summary.

Useful connection checks:

curl http://localhost:8088/api/

On Windows:

Invoke-WebRequest -UseBasicParsing http://localhost:8088/api/
Test-NetConnection localhost -Port 8099

Release Shape

CueScope should demonstrate value without live execution:

1. Connect to vMix.
2. Analyze the current preset.
3. Diagnose a realistic audio scenario.
4. Generate and validate a script using actual input references.
5. Compare before and after XML snapshots.
6. Keep Control Mode and High-Impact Control available but secondary.

License

CueScope Source-Available License - see LICENSE for details. Official releases may be installed and used for personal, internal, production, broadcast, educational, nonprofit, and commercial live-production workflows. Redistribution, competing products or services, hosted/managed offerings, and broader reuse require written permission from Greenhouse Ventures LLC.

Support

• Contributing Guide
• Security Policy
• Changelog
• Third-Party Notices
• vMix Forums
• MCP Documentation
• GitHub Issues

Built for the live production community by Greenhouse Labs.