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.

Related MCP server: checkyourself

What It Does

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

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.

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.

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.

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

Resources

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.

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.