Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@vmix-workbench-mcp Build a quad of cameras 1-4, preview it, then update the score title to 15:12."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
让 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 慢放速度。
托管触发器运行在 MCP 进程中，不会写入 vMix 原生 Triggers 列表。 进程关闭即停止；重启后定义保留，但全部未启用。250ms 默认轮询不能保证帧级触发，也可能错过两次读取之间的短暂事件。
导入路径不等于上传文件。 同机部署可以直接读本机素材；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 配置示例 中的代码目录、素材目录改成真实路径，加入支持 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 素材目录：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：
检查当前 vMix 工程，找到四路摄像机。以 3840×2160 的当前工程尺寸搭建四宫格，先展示 dry-run；确认输入名称后创建。把第一个转场按钮设为 500ms Fade，先留在预览，不要上屏。
把素材目录中的选手介绍图暂存后导入 vMix，告诉我新输入的 GUID。找到比分标题的实际字段，把比分改为 15 : 12，并查询结果。
创建一个托管触发器：主机位进入节目画面后，在 Overlay 1 显示比分。先保存为未启用，列出动作，然后按我的指令启用。
完整调用示例：羽毛球工作流。所有名字必须替换为实际工程中的唯一名字，或使用 GUID。模板尺寸必须匹配当前 vMix 工程；工具不会自动修改输出分辨率。
工具 | 用途 |
| 读取工程状态、输入身份及字段 |
| 查询持久化操作结果 |
| 有序执行经过校验的动作组合 |
| 按实际字段名批量更新字幕 |
| 暂存/校验素材，返回 vMix 可见路径 |
| 导入素材或创建色板，返回新 GUID |
| 创建自定义多层画面 |
| 创建 full / two_up / quad / pip 模板画面 |
| 设置原生转场按钮及 GT Stinger 绑定 |
| 保存 MCP 命名转场预设 |
| 使用预设切到指定输入 |
| 保存未启用的托管触发器 |
| 启用/停用，取消待执行延迟动作 |
| 停用并删除托管定义 |
| 查看预设、触发器及运行状态 |
| 生成尚未自动应用的原生设置步骤 |
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 也不拥有官方比赛比分规则或自动判断精彩球。
环境变量 | 默认值 / 说明 |
|
|
|
|
|
|
|
|
| 启动工作目录下 |
| 允许读取的素材目录 JSON 数组，默认启动目录 |
| 数据目录下 |
| 默认同上；可映射为 Windows 可见目录 |
| 可选 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-runnpm test 使用真实 MCP SDK 与本机模拟 HTTP 服务，覆盖素材、场景、字段、转场、重复请求、失败与托管触发器。npm run smoke 启动真实 stdio 子进程，验证工具发现、四宫格创建和切换。测试不会访问现场 vMix。npm run mock 可单独启动模拟服务（默认 8098 端口）。
GitHub CI 覆盖 Windows/Linux、Node 22/24；CI 与模拟测试均不能替代真实 vMix 的节目画面验收。详细边界见 架构与验收。
仓库未复制此前审查的第三方 vMix MCP 源码、知识库或示例实现。
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.
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.
List saved transition presets and MCP-managed triggers, including armed state.
Inputs: no named parameters.
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.
Read real vMix inputs, GUIDs, title fields, layers, program, preview and overlays.
Inputs: no named parameters.
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.
Get persisted operation status. Same request_id is never executed twice, including after restart.
Inputs: request_id (required).
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.
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.
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.
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.
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.
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.
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).
Disarm and remove an MCP-managed trigger definition.
Inputs: id (required).
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.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 16 tools
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).
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.
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.
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.
Build and run visual creative-production workflows from your AI agent.
AI video editor your agent can drive: plan scenes, edit a multi-track timeline, and render MP4s.
Video production studio for AI agents: AI media, motion graphics as code, timeline and export.
Control evmux live streaming studios: scenes, layers, participants, media, banners and broadcast.
