Q-SYS MCP

qsys-tools

面向 QSC Q-SYS 音视频系统的开源工具——从命令行或代码控制 Core，或借助 AI Agent 控制，也可以在 Mac 上原生运行 Q-SYS Designer。

每台 Q-SYS Core 以及处于 Emulate mode 的 Q-SYS Designer，都会提供 QSC 发布的 QRC 协议（通过 TCP 端口 1710 传输的 JSON-RPC 2.0）。它与 Crestron/AMX 集成所用的是同一种外部控制接口。这些工具可直接使用该协议：无需 QSC 代码、无需 SDK，开发时也无需硬件。

软件包	简介
qsys-cli	命令行工具（命令：qsys）——查看状态和组件清单、获取/设置控件（支持渐变）、实时监视、保存快照
qsys-qrc	TypeScript QRC 客户端——线路帧处理、变更组、保活、透明自动重连、类型化协议接口
qsys-mcp	MCP 服务（在 MCP Registry 中的标识为 io.github.reowens/qsys-mcp）——提供 18 种工具，让 AI Agent 检查并控制正在运行的 Q-SYS 系统
qsys-mac	npm 引导程序（命令：qsys-mac）——下载并验证已签名的 Q-SYS Mac Installer DMG，然后调用其中的辅助程序
qsys-mac-installer	适用于 macOS 的 Q-SYS Designer——已签名并公证的自带安装程序封装应用 + DMG 源码

快速开始——命令行

export QSYS_HOST=192.168.1.10     # your Core, or 127.0.0.1 for Designer Emulate

npx qsys-cli status               # engine/design status
npx qsys-cli ls                   # list components
npx qsys-cli get MainGain         # read a named control
npx qsys-cli set MainGain -6 --ramp 2
npx qsys-cli watch MainGain       # stream changes until Ctrl-C
npx qsys-cli snapshot load Bank 1 --ramp 1

$ qsys status
Design     RobertOwens-L1 (code Hd4b6C9TXKzL)
Platform   Emulator (emulator)
State      Active

$ qsys set-component Main_Mixer input.1.gain -6 --ramp 2
NAME          VALUE  STRING   POSITION
input.1.gain  -6     -6.00dB  0.585

使用 npm i -g qsys-cli 全局安装命令；其可执行文件名为 qsys。 每条命令都支持用于脚本处理的 --json；watch 会输出 JSON 行。

快速开始——AI Agent（MCP）

claude mcp add qsys -- npx -y qsys-mcp

也可以在任意 MCP 客户端配置中添加：

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

然后让 Agent 连接到你的 Core（或 Designer 模拟器），即可读取电平表、切换静音、渐变调节增益、监视控件变化并调用快照——即使 Core 重启，也会自动重新连接。详情请参阅 packages/qsys-mcp。

支持 Registry 的 MCP 客户端可以通过 io.github.reowens/qsys-mcp 发现该服务。

快速开始——在自己的代码中使用

npm install qsys-qrc

import { QrcClient } from 'qsys-qrc';

const qrc = new QrcClient({ host: '192.168.1.10' });
await qrc.connect();

const status = await qrc.statusGet();          // typed helpers…
await qrc.setControl('MainGain', -6, 2);       // value -6, 2 s ramp
const [gain] = await qrc.getControl(['MainGain']);

await qrc.send('Component.GetComponents');     // …or raw QRC methods

qrc.close();

变更组（基于轮询的监视）、组件访问、快照和登录均由类型化辅助函数支持——请参阅 packages/qsys-qrc。

在 Mac 上使用 Q-SYS Designer

对于大多数用户，请使用已签名的 DMG 安装器应用。运行一次即可创建 Q-SYS Designer.app，然后 可以删除安装器应用，也可以保留它，作为用于启动、重新安装和移除的小型管理工具。 已安装的 Designer 应用及其 Application Support 数据独立于安装器应用。

直接使用 DMG 的方式：

open https://github.com/reowens/qsys-tools/releases/tag/qsys-mac-installer-v0.1.4

或者使用 npm 引导程序：

npx qsys-mac install "/path/to/Q-SYS Designer Installer 10.4.0.exe"

它会下载并验证已签名的 Q-SYS Mac Installer DMG，挂载该文件，然后运行 其中捆绑的辅助程序。npm 软件包不包含 Q-SYS Designer 或应用程序 载荷。你需要提供自己的免费 Designer 安装器下载（BYO——不再分发 QSC 的任何内容）。

如需只读支持诊断，请运行：

npx qsys-mac doctor

当前 macOS 前置要求：Rosetta 2。已签名的 DMG 捆绑了 Wine、.NET、7z、 图标工具、msiinfo 和原生辅助二进制文件；正常安装无需 Homebrew 或主机上的 Python。

更喜欢 GUI 安装器应用？可以使用 Homebrew 安装：

brew tap reowens/qsys
brew trust reowens/qsys
brew install --cask qsys-mac-installer
open -a "Q-SYS Mac Installer"

当前版本的 Homebrew 要求第三方 cask tap 使用 brew trust。

已签名安装器的源代码位于 packages/qsys-mac-installer。它会将 Wine + .NET 安装到 Application Support 中，并让应用成为真正融入 Dock、Finder 和菜单栏的应用。 当前已签名的 DMG 为 qsys-mac-installer 0.1.4。

额外说明：Designer 的仿真模式会在 127.0.0.1:1710 上提供 QRC 服务，因此上述所有 工具都能在无需硬件的情况下对其运行——本仓库中的工具正是通过这种方式 进行验证的。

没有硬件？

将任何工具指向以仿真模式运行的 Q-SYS Designer（--host 127.0.0.1）。有两个协议细节值得了解：QRC 没有用于枚举 命名控件或快照库的方法（你需要从设计中获取它们的名称），而 Component.GetComponents 只会返回启用了脚本访问权限的组件。

开发

这是一个 pnpm 工作区（Node 22.13+；pnpm 通过 corepack 从 packageManager 字段获取）。

git clone https://github.com/reowens/qsys-tools.git
cd qsys-tools
corepack enable        # provisions the pinned pnpm
pnpm install
pnpm -r build          # builds packages in dependency order (qsys-qrc first)
pnpm run typecheck
pnpm test

端到端测试套件（QRC 集成、基于模拟器的 MCP 端到端测试，以及透明重连／AutoPoll 重放回归测试）针对 qsys-mock-core 运行——这是仓库内由设计驱动的 Q-SYS Core 模拟器——因此 pnpm test 无需硬件即可测试完整协议。更深入的一致性测试（基于 Designer 验证的渲染、渐变／仪表，以及真实 Q-SYS 设计库）使用单独且功能更完整的模拟器。

qsys-mac-installer 使用 Xcode 单独构建——参见 packages/qsys-mac-installer（签名／公证流程见 scripts/package.sh）。

维护者的发布步骤记录在 RELEASE.md 中。

在此源代码检出目录中操作时，请使用工作区脚本，而不要使用 npx qsys-mac，以免本地工作区软件包与已发布的软件包混淆：

pnpm run qsys-mac -- status
pnpm run qsys-mac -- install "/path/to/Q-SYS Designer Installer 10.4.0.exe"

许可

原始 qsys-tools 源代码采用 MIT 许可，包括 QRC 软件包、 qsys-mac npm 引导程序和 qsys-mac-installer 封装应用。

已签名的 macOS 安装器 DMG 是采用多种许可的二进制发行版，因为它捆绑了 Wine、.NET、p7zip、icoutils、msiinfo 及其运行时库等可再分发的第三方组件。这些 组件仍受各自的许可和声明约束；请参阅 packages/qsys-mac-installer/THIRD-PARTY-NOTICES.md。

每个软件包都包含自己的 LICENSE 文件。

免责声明

这是一个独立的开源项目，与 QSC, LLC 无关联，未获其认可，也未受其赞助。“Q-SYS”和“Q-SYS Designer”是 QSC, LLC 的商标， 在此仅作为名称使用。这些工具使用公开记录的 QRC 协议， 不包含任何 QSC 代码。