Skip to main content
Glama

vMix Workbench MCP

让 Agent 通过 MCP 检查 vMix、导入素材、搭建多层画面、修改字幕、配置原生转场,并创建可运行的托管触发器。

V0.1:独立依据 vMix 官方 API 实现。已通过模拟 vMix 与真实 MCP stdio 客户端测试;真实 Windows/vMix 画面验收仍待完成。

能做什么

  • 检查工程:输入 GUID、名字、字幕文字/图片字段、图层、Preview、Program、叠加层。

  • 素材暂存和导入:本机文件复制、SHA-256 校验、Windows 共享目录映射;导入视频、图片、GT 标题、音频和色板。

  • 搭画面:全屏、双画面、四宫格、画中画模板,或最多 10 层的自定义矩形与裁切。

  • 图文与播放:批量更新字幕、替换图片、叠加层显隐、播放/暂停/循环、音量与静音。

  • 原生转场设置:四个转场按钮的效果与时长;GT Stinger 1–8 动画源绑定;保存常用 MCP 转场预设并执行。

  • 托管触发器:观察节目/叠加状态变化、播放暂停或时间跨越,按顺序执行动作;支持保存、启用、停用和取消延迟动作。

  • 基本回放命令:标记最近 N 秒、指定 A/B 通道播放/暂停、0–1 慢放速度。

两个区别

  1. 托管触发器运行在 MCP 进程中,不会写入 vMix 原生 Triggers 列表。 进程关闭即停止;重启后定义保留,但全部未启用。250ms 默认轮询不能保证帧级触发,也可能错过两次读取之间的短暂事件。

  2. 导入路径不等于上传文件。 同机部署可以直接读本机素材;Mac 远控 Windows 时,要配置已挂载的共享目录,或先把素材复制到 Windows 再导入。

普通视频/图片序列 Stinger 的原生动画源、切点,以及原生触发器列表编辑没有在此实现中假定存在 API。vmix_native_setup_guide 会输出具体设置步骤,明确 applied:false。GT Stinger 的时间来自 GT 动画本身。

Related MCP server: DualStream MCP Server

安装

需要 Node.js 22 或以上。vMix API 基线为官方 v29 文档;实际版本的支持情况要通过目标工程确认。

git clone https://github.com/chendpoc/vmix-workbench-mcp.git
cd vmix-workbench-mcp
npm ci --ignore-scripts
npm run build

在 vMix 的 Settings → Web 中启用 Web Controller,确认本机能访问其 /api/ 并返回 vMix XML。首次接入建议设置 VMIX_READ_ONLY=true,先调用 vmix_inspect 核对工程,再设为 false 开启写操作。此项目不会改动现有客户端配置。

Windows 本机运行(最简单)

把 Windows 配置示例 中的代码目录、素材目录改成真实路径,加入支持 mcpServers 的客户端。MCP 启动命令使用 node .../build/index.js,不要使用 npm start 作为 stdio 客户端启动命令,因为 npm 的输出可能混入协议流。

Codex CLI 可用下面的命令登记(路径请替换;--env 可重复):

codex mcp add vmix --env VMIX_API_URL=http://127.0.0.1:8088/api/ --env VMIX_DATA_DIR=C:\vMixMCP\state --env VMIX_ASSET_ROOT=C:\vMixMCP\assets -- node C:\tools\vmix-workbench-mcp\build\index.js

素材暂存默认只读取启动工作目录。使用 vmix_asset_stage 前,把 VMIX_SOURCE_ROOTS 设置为允许读取的素材目录 JSON 数组;完整可复制的转义写法见配置示例文件。

Mac 通过局域网控制 Windows

使用 Mac 配置示例。例如:

  • Windows 素材目录:D:\vMixAssets。

  • 同一目录通过 SMB 挂载到 Mac:/Volumes/vMixAssets。

  • VMIX_ASSET_ROOT=/Volumes/vMixAssets。

  • VMIX_VISIBLE_ASSET_ROOT=D:\vMixAssets。

vmix_asset_stage 会把本机素材复制到共享目录,并返回 Windows 端的 vmix_path;随后将该路径交给 vmix_input_add。没有共享挂载时,仅填写 Windows 路径不会传输文件。

一个工程只运行一个有写权限的 MCP 实例。局域网访问 vMix 时按现有网络与 Web Controller 认证配置开放连接,不把控制 API 暴露到公网。

让 Agent 开始工作

可以直接告诉 Agent:

检查当前 vMix 工程,找到四路摄像机。以 3840×2160 的当前工程尺寸搭建四宫格,先展示 dry-run;确认输入名称后创建。把第一个转场按钮设为 500ms Fade,先留在预览,不要上屏。

把素材目录中的选手介绍图暂存后导入 vMix,告诉我新输入的 GUID。找到比分标题的实际字段,把比分改为 15 : 12,并查询结果。

创建一个托管触发器:主机位进入节目画面后,在 Overlay 1 显示比分。先保存为未启用,列出动作,然后按我的指令启用。

完整调用示例:羽毛球工作流。所有名字必须替换为实际工程中的唯一名字,或使用 GUID。模板尺寸必须匹配当前 vMix 工程;工具不会自动修改输出分辨率。

工具列表

工具

用途

vmix_inspect

读取工程状态、输入身份及字段

vmix_operation_get

查询持久化操作结果

vmix_actions

有序执行经过校验的动作组合

vmix_title_update

按实际字段名批量更新字幕

vmix_asset_stage

暂存/校验素材,返回 vMix 可见路径

vmix_input_add

导入素材或创建色板,返回新 GUID

vmix_scene_create

创建自定义多层画面

vmix_scene_template

创建 full / two_up / quad / pip 模板画面

vmix_transition_configure

设置原生转场按钮及 GT Stinger 绑定

vmix_transition_preset_save

保存 MCP 命名转场预设

vmix_transition

使用预设切到指定输入

vmix_trigger_save

保存未启用的托管触发器

vmix_trigger_arm

启用/停用,取消待执行延迟动作

vmix_trigger_delete

停用并删除托管定义

vmix_configuration

查看预设、触发器及运行状态

vmix_native_setup_guide

生成尚未自动应用的原生设置步骤

vmix_actions 中允许的动作:preview、transition、overlay、text、image、playback、audio、layer、transition_button、stinger_gt、replay、wait。不提供任意脚本、系统命令或无约束的 vMix Function 工具。

结果与恢复

每次实际控制请求都需要 request_id。重复提交同一 ID/参数返回原结果,重启也不重做;同一 ID/不同参数拒绝。dry_run:true 不占用 ID,可先预览再用同一 ID 执行。

  • completed:计划步骤执行结束。逐步查看 verification;state_observed 与仅 api_accepted 有区别。

  • unconfirmed:命令可能已经影响 vMix,但结果未可靠确认。检查 vmix_inspect、vmix_operation_get 和实际画面,不能换个 ID 盲目重试。

  • partial / failed:查看已完成步骤与错误。工具不会为了回滚而自动删除已创建的输入。

创建输入只能通过前后状态差识别新 GUID。搭建期间不要让另一个操作者同时新增输入。 发现多个新输入或类型不符会停止;这个 API 没有提供创建事务标识,外部并发无法完全消除。

多字段字幕更新不是原子画面事务。图层位置、GT 动画是否正确、实际音频及 4K 性能须在 vMix 中监看。此 MCP 也不拥有官方比赛比分规则或自动判断精彩球。

配置

环境变量

默认值 / 说明

VMIX_API_URL

http://127.0.0.1:8088/api/,固定控制目标

VMIX_READ_ONLY

false;true 禁止写入,仍可 dry-run

VMIX_TIMEOUT_MS

5000,完整 HTTP 响应的期限

VMIX_POLL_MS

250,托管触发器轮询间隔

VMIX_DATA_DIR

启动工作目录下 .vmix-mcp,配置与操作记录

VMIX_SOURCE_ROOTS

允许读取的素材目录 JSON 数组,默认启动目录

VMIX_ASSET_ROOT

数据目录下 assets,MCP 主机实际复制目标

VMIX_VISIBLE_ASSET_ROOT

默认同上;可映射为 Windows 可见目录

VMIX_API_USERNAME / VMIX_API_PASSWORD

可选 Basic Authorization;仅用于目标接受这种认证时

每个数据目录有进程锁。服务会回收已确认死亡的本机进程锁;活跃、未知或其他主机的锁不会自动删除。锁损坏或遗留 recovery.lock 时,先确认没有该目录的服务进程,再处理锁文件;不要删除 state.json 来“修复连接”,它保存重复请求记录与配置。正常关闭会释放锁。数据目录应位于本机磁盘,素材目录才使用共享挂载。

托管触发器默认每次启用只执行一次,最高可配置 100 次;重连只建立新观察基线,不补发历史事件。playback_stopped 包含人工暂停,不等于原生 OnCompletion;playback_time 可能由拖动进度条跨越触发。需要精确播放完成事件时,使用原生 vMix 触发器。

开发验证

npm test
npm run smoke
npm run format:check
npm pack --dry-run

npm test 使用真实 MCP SDK 与本机模拟 HTTP 服务,覆盖素材、场景、字段、转场、重复请求、失败与托管触发器。npm run smoke 启动真实 stdio 子进程,验证工具发现、四宫格创建和切换。测试不会访问现场 vMix。npm run mock 可单独启动模拟服务(默认 8098 端口)。

GitHub CI 覆盖 Windows/Linux、Node 22/24;CI 与模拟测试均不能替代真实 vMix 的节目画面验收。详细边界见 架构与验收。

官方接口依据

仓库未复制此前审查的第三方 vMix MCP 源码、知识库或示例实现。

Available Tools

16 tools
vmix_actionsA
Destructive

Run up to 20 typed actions in order. Supports preview, transition, overlay, text/image, playback/audio, layers, native transition buttons, GT stinger binding and replay. No arbitrary API function.

Inputs: actions (required), request_id (required), dry_run.

vmix_asset_stageA
Destructive

Copy a local media file into the configured asset directory with a SHA-256 filename. VMIX_VISIBLE_ASSET_ROOT can map a Mac-mounted Windows share. Does not import into vMix.

Inputs: source_path (required), dry_run.

vmix_configurationA
Read-only

List saved transition presets and MCP-managed triggers, including armed state.

Inputs: no named parameters.

vmix_input_addA
Destructive

Import a file already visible to vMix, or create a colour input. Returns discovered GUID. Use asset_stage first when bytes need copying. Does not take the input on air.

Inputs: type (required), value (required), request_id (required), name, +1 more.

vmix_inspectA
Read-only

Read real vMix inputs, GUIDs, title fields, layers, program, preview and overlays.

Inputs: no named parameters.

vmix_native_setup_guideA
Read-only

Produce concrete native vMix setup steps for a trigger or non-GT Stinger. Read-only: these unsupported settings are NOT written into vMix.

Inputs: kind (required), input (required), slot, event, +3 more.

vmix_operation_getA
Read-only

Get persisted operation status. Same request_id is never executed twice, including after restart.

Inputs: request_id (required).

vmix_scene_createB
Destructive

Build an off-air colour-backed scene from existing inputs, with up to 10 layers, pixel rectangles and crop. Pixel coordinates are based on the vMix preset resolution. Never removes inputs on failure.

Inputs: name (required), layers (required), request_id (required), dry_run, +1 more.

vmix_scene_templateA
Destructive

Build a full, two_up, quad or picture-in-picture scene. Sources must already exist. Canvas dimensions must match your vMix preset; this tool does not change output resolution.

Inputs: name (required), layout (required), sources (required), request_id (required), +3 more.

vmix_title_updateA
Destructive

Update named text fields on a title input. Inspect exact field names first (GT uses .Text). All fields validate before writing; multiple updates are ordered, not a frame-atomic transaction.

Inputs: input (required), fields (required), request_id (required), dry_run.

vmix_transitionC
Destructive

Take a specified input on the main program using a saved MCP transition preset; returns state confirmation.

Inputs: input (required), preset (required), request_id (required), dry_run.

vmix_transition_configureA
Destructive

Configure one of the four native vMix transition buttons: effect and duration. Optionally bind a GT title input to a Stinger slot. Native writes via documented API.

Inputs: button (required), effect (required), request_id (required), duration_ms (required), +3 more.

vmix_transition_preset_saveA
Destructive

Save a reusable MCP transition preset. Also use transition_configure if you want to modify a native vMix button.

Inputs: name (required), effect (required), duration_ms (required), dry_run.

vmix_trigger_armA
Destructive

Explicitly arm/disarm a saved managed trigger. No startup/reconnect event catch-up; restarting MCP disarms all triggers. Disarming cancels pending delayed actions.

Inputs: id (required), armed (required).

vmix_trigger_deleteC
Destructive

Disarm and remove an MCP-managed trigger definition.

Inputs: id (required).

vmix_trigger_saveA
Destructive

Save a DISARMED MCP-managed trigger. Events are polled state changes, not native vMix triggers. playback_stopped includes manual pauses; playback_time can detect seeks. Default one-shot per arm.

Inputs: trigger (required), dry_run.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 16 tools

    Disambiguation4/5

    Most tools map to a distinct resource+action pair, and the descriptions are detailed enough to guide selection. The main overlaps are vmix_actions vs. vmix_transition (both can perform transitions) and vmix_scene_create vs. vmix_scene_template (both build scenes).

    Naming Consistency4/5

    All tools share the vmix_ prefix and snake_case, and most follow an area_action pattern like vmix_title_update or vmix_trigger_arm. A few bare nouns (vmix_inspect, vmix_actions, vmix_transition, vmix_configuration) and noun-noun names break the otherwise consistent pattern.

    Tool Count4/5

    16 tools is at the upper edge of acceptable for a vMix workbench covering inspection, operations, actions, scenes, transitions, triggers, assets, and setup guidance. The count is slightly heavy but each tool covers a real part of the workflow.

    Completeness3/5

    Core creation and control workflows are well covered, including inputs, scenes, transitions, triggers, and actions. However, there are notable lifecycle gaps: no removal/cleanup for inputs, scenes, assets, or transition presets, and scene creation is one-shot with no update path.

    Maintenance

    ActivityStale
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers