Q-SYS MCP

io.github.reowens由 GitHub 帳號 reowens 發布v0.6.1更新於 Nov 6, 2026

Control QSC Q-SYS systems over QRC from AI agents or Claude.

概覽

AI 產生的概覽

讓 AI 助理透過 QRC 連線 QSC Q-SYS Core 或 Designer 模擬器,檢視、調整並監控影音控制項。

可以做什麼
  • 連線 Core 或 Designer 模擬器並讀取引擎狀態
  • 列出元件,讀取其控制項與目前值
  • 設定具名控制項與元件內控制值,可加上漸變
  • 載入與儲存快照,並操作混音器交叉點、輸入、輸出與提示
  • 啟動、停止與取消 Loop Player 音訊播放
  • 建立、輪詢、裁剪與銷毀變更群組,以監控控制項變化
適用情境
適用於使用 Q-SYS 影音系統的情境:希望助理讀取電平表與控制值、調整增益與靜音、載入快照,或監控控制項變化;也可在沒有硬體時對 Designer 的模擬模式使用。
執行需求
以 npm 套件 qsys-mcp 透過 npx 在本機執行,需要 Node.js。需能透過網路連線到 Q-SYS Core 或處於模擬模式的 Q-SYS Designer 的 TCP 1710 埠,主機與埠在連線工具中傳入。未宣告 API 金鑰或環境變數。
安裝前請注意
多個工具會改動實際系統:設定控制項、混音器增益與靜音、載入快照和 Loop Player 播放都會改變執行中或模擬中的設計,儲存快照會覆蓋原有快照。建議先在模擬器上試用。QRC 無法列舉具名控制項或快照庫,且只能看到已啟用腳本存取的元件。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Q-SYS MCP,將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only,透過 STDIO。 STDIO 服務會啟動本機處理程序,因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

README

qsys-tools

Open-source tooling for QSC Q-SYS audio/video systems — control a Core from your shell, your code, or an AI agent, and run Q-SYS Designer on your Mac or Ubuntu desktop.

[npm qsys-cli] [npm qsys-qrc] [npm qsys-mcp] [npm qsys-mac] [npm qsys-linux] [node ≥18] [license: MIT]

Every Q-SYS Core — and Q-SYS Designer in Emulate mode — serves QSC's published QRC protocol (JSON-RPC 2.0 over TCP, port 1710). It's the same external-control interface Crestron/AMX integrations use. These tools speak it natively: zero QSC code, no SDK, no hardware required for development.

PackageWhat it is
qsys-cliCLI (command: qsys) — status, component inventory, get/set controls with ramps, live watch, snapshots
qsys-qrcTypeScript QRC client — wire framing, change groups, keepalive, transparent auto-reconnect, typed protocol surface
qsys-mcpMCP server (io.github.reowens/qsys-mcp in the MCP Registry) — 25 tools that let an AI agent inspect and drive a live Q-SYS system
qsys-macnpm bootstrapper (command: qsys-mac) — downloads/verifies the signed Q-SYS Mac Installer DMG and delegates to its helper
qsys-mac-installerQ-SYS Designer for macOS — signed/notarized BYO-installer wrapper app + DMG source
qsys-linuxQ-SYS Designer for Ubuntu 26.04 x86-64 — per-user Wine/.NET 10 setup and desktop launcher (command: qsys-linux)

Quick start — shell

sh
export QSYS_HOST=192.168.1.10     # your Core, or 127.0.0.1 for Designer Emulate
npx qsys-cli status               # engine/design statusnpx qsys-cli ls                   # list componentsnpx qsys-cli get MainGain         # read a named controlnpx qsys-cli set MainGain -6 --ramp 2npx qsys-cli watch MainGain       # stream changes until Ctrl-Cnpx qsys-cli snapshot load Bank 1 --ramp 1
$ qsys statusDesign     Example-Design (code a1B2c3D4e5F6)Platform   Emulator (emulator)State      Active
$ qsys set-component Main_Mixer input.1.gain -6 --ramp 2NAME          VALUE  STRING   POSITIONinput.1.gain  -6     -6.00dB  0.585

Install the command globally with npm i -g qsys-cli (the binary is plain qsys). Every command takes --json for scripting; watch emits JSON lines.

Quick start — AI agent (MCP)

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

or in any MCP client config:

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

Then ask the agent to connect to your Core (or the Designer emulator) and it can read meters, flip mutes, ramp gains, watch controls for changes, and recall snapshots — with auto-reconnect across Core restarts. Details in packages/qsys-mcp.

Registry-aware MCP clients can discover it as io.github.reowens/qsys-mcp.

Quick start — your own code

sh
npm install qsys-qrc
ts
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 rampconst [gain] = await qrc.getControl(['MainGain']);
await qrc.send('Component.GetComponents');     // …or raw QRC methods
qrc.close();

Change groups (poll-based watch), component access, snapshots, and logon are all covered by typed helpers — see packages/qsys-qrc.

Q-SYS Designer on your Mac

For most users, use the signed DMG installer app. Run it once to create Q-SYS Designer.app, then either trash the installer app or keep it around as a small manager for Launch, Reinstall, and Remove. The installed Designer app and its Application Support data remain independent of the installer app.

Direct DMG path:

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

Or use the npm bootstrapper:

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

It downloads and verifies the signed Q-SYS Mac Installer DMG, mounts it, and runs the bundled helper. The npm package does not contain Q-SYS Designer or the app payload. You provide your own free Designer installer download (BYO — nothing of QSC's is redistributed).

For read-only support diagnostics, run:

sh
npx qsys-mac doctor

Current macOS prerequisite: Rosetta 2. The signed DMG bundles Wine, .NET, 7z, icon tooling, msiinfo, and native helper binaries; normal setup does not need Homebrew or host Python.

Prefer a GUI installer app? Homebrew can install it:

sh
brew tap reowens/qsysbrew trust reowens/qsysbrew install --cask qsys-mac-installeropen -a "Q-SYS Mac Installer"

brew trust is required by current Homebrew for third-party cask taps.

The signed installer source lives in packages/qsys-mac-installer. It provisions Wine + .NET into Application Support and gives you a real Dock/Finder/menu-bar citizen. The current signed DMG is qsys-mac-installer 0.1.11.

Bonus: Designer's Emulate mode serves QRC on 127.0.0.1:1710, so all of the tools above work hardware-free against it — that's how this repo's tooling is validated.

Q-SYS Designer on Linux

The initial Linux recipe runs Designer 10.5.1 on Ubuntu 26.04 x86-64 through Wine Staging 11.20 and Windows .NET 10. Supply your own vendor ZIP/EXE:

sh
npx qsys-linux install "/path/to/Q-SYS_Designer_Installer_10.5.1.zip"npx qsys-linux doctornpx qsys-linux launch

Installation needs an accessible X11/XWayland desktop and 12 GiB free during setup. It runs per-user without sudo and adds a Q-SYS Designer desktop launcher. See requirements and validation.

The source checkout also has a vendor-free Docker test harness, described under Container smoke tests. You build its image locally; no image is published.

No hardware?

Point any of the tools at Q-SYS Designer running in Emulate mode (--host 127.0.0.1). Two protocol facts worth knowing: QRC has no method to enumerate named controls or snapshot banks (you need their names from the design), and Component.GetComponents returns only components with script access enabled.

Development

This is a pnpm workspace (Node 22.13+; pnpm comes from the packageManager field via corepack).

sh
git clone https://github.com/reowens/qsys-tools.gitcd qsys-toolscorepack enable        # provisions the pinned pnpmpnpm installpnpm -r build          # builds packages in dependency order (qsys-qrc first)pnpm run typecheckpnpm test

The e2e suites (QRC integration, the MCP-over-mock end-to-end, and the transparent-reconnect/AutoPoll-replay regression) run against qsys-mock-core — an in-repo, design-driven Q-SYS Core mock — so pnpm test exercises the full protocol with no hardware. Deeper conformance testing (validated-against-Designer rendering and ramps/meters) uses a separate, fuller emulator.

qsys-mac-installer builds separately with Xcode — see packages/qsys-mac-installer (scripts/package.sh for the sign/notarize pipeline).

Maintainer release steps are documented in RELEASE.md.

When working from this source checkout, use the workspace script instead of npx qsys-mac so the local workspace package isn't confused with the published one:

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

Licensing

The original qsys-tools source code is MIT licensed, including the QRC packages, the qsys-mac npm bootstrapper, the qsys-linux recipe, and the qsys-mac-installer wrapper app.

The signed macOS installer DMG is a multi-license binary distribution because it bundles redistributable third-party components such as Wine, .NET, p7zip, icoutils, msiinfo, and their runtime libraries. Those components remain under their own licenses and notices; see packages/qsys-mac-installer/THIRD-PARTY-NOTICES.md.

Each package carries its own LICENSE file.

Disclaimer

This is an independent open-source project, not affiliated with, endorsed by, or sponsored by QSC, LLC. "Q-SYS" and "Q-SYS Designer" are trademarks of QSC, LLC, used nominatively. These tools speak the publicly documented QRC protocol and contain no QSC code.

來源:README.md,提交 0057e21

工具

25

qsys_connect

Connect to Q-SYS

Connect to a Q-SYS Core or to Q-SYS Designer running in Emulate mode (press F6 in Designer), over the QRC protocol (TCP). For a local emulator use host "127.0.0.1" and port 1710. Must be called before any other tool.

輸入參數hostportuserpasswordreconnectallow_live_writes

qsys_status

Q-SYS engine status

Get the Q-SYS engine status: platform, design name, run state, emulator flag.

無需輸入參數。

qsys_list_components

List components

List named components in the running/emulated design, with type and properties (Component.GetComponents). On large designs use filter/type/names_only to trim the response. Note: QRC only sees components whose Designer "Script Access" is set to External or All (None is the default) — a component missing here, or one that silently ignores writes, most likely needs its Code Name + Script Access set in Designer.

輸入參數typefilternames_only

qsys_get_component_controls

Get component controls

List a named component's controls and current values (Component.GetControls). Use filter/names_only to trim large components.

輸入參數name必填filternames_only

qsys_get_control

Get control values

Get the current values of one or more Named Controls (Control.Get).

輸入參數names必填

qsys_get_component

Get specific component control values

Get specific control values within a named component (Component.Get).

輸入參數name必填controls必填

qsys_set_control

Set a control value

Set a Named Control value, optionally ramped over a number of seconds (Control.Set). This MUTATES the running/emulated system.

輸入參數name必填rampvalue必填

qsys_set_component

Set component control values

Set one or more control values within a named component, each optionally ramped (Component.Set). This MUTATES the running/emulated system.

輸入參數name必填controls必填

qsys_load_snapshot

Recall a snapshot

Recall control settings from a saved snapshot bank/number, optionally ramped over seconds (Snapshot.Load). This MUTATES the running/emulated system.

輸入參數bank必填rampnumber必填

qsys_save_snapshot

Save a snapshot

Capture the current control settings into a snapshot bank/number (Snapshot.Save). This OVERWRITES the stored snapshot.

輸入參數bank必填number必填

qsys_mixer_set_crosspoint

Set mixer crosspoint(s)

Set gain/delay (number, ramped) or mute/solo (boolean) on the crosspoints of an input×output selection (Mixer.SetCrossPoint{Gain,Delay,Mute,Solo}). This MUTATES the running/emulated system. Read mixer state back via qsys_get_component.

輸入參數op必填name必填rampvalue必填inputs必填outputs必填

qsys_mixer_set_input

Set mixer input(s)

Set gain (number, ramped) or mute/solo (boolean) on selected mixer inputs (Mixer.SetInput{Gain,Mute,Solo}). This MUTATES the running/emulated system. Read mixer state back via qsys_get_component.

輸入參數op必填name必填rampvalue必填inputs必填

qsys_mixer_set_output

Set mixer output(s)

Set gain (number, ramped) or mute (boolean) on selected mixer outputs (Mixer.SetOutput{Gain,Mute}). This MUTATES the running/emulated system. Read mixer state back via qsys_get_component.

輸入參數op必填name必填rampvalue必填outputs必填

qsys_mixer_set_cue

Set mixer cue(s)

Set gain (number, ramped) or mute (boolean) on selected mixer cues (Mixer.SetCue{Gain,Mute}). This MUTATES the running/emulated system. Read mixer state back via qsys_get_component.

輸入參數op必填cues必填name必填rampvalue必填

qsys_mixer_set_cue_input

Route/monitor input(s) to cue(s)

Enable an input on a cue, or set its AFL (after-fade listen) flag (boolean) (Mixer.SetInputCue{Enable,Afl}). This MUTATES the running/emulated system. Read mixer state back via qsys_get_component.

輸入參數op必填cues必填name必填value必填inputs必填

qsys_loop_player_start

Start Loop Player playback

Schedule one or more audio files to play on a Loop Player component (LoopPlayer.Start). This MUTATES the running/emulated system. There is no QRC method to browse Core files — pass a file path you already know. Read Loop Player state back via qsys_get_component.

輸入參數logloopname必填seekfiles必填refIdstartTime

qsys_loop_player_stop_cancel

Stop or cancel Loop Player playback

Stop current playback on outputs (op "stop"), or cancel a pending/queued future-start job without disrupting current playback (op "cancel") — LoopPlayer.Stop / LoopPlayer.Cancel. Outputs is a list of integer output numbers (e.g. [1, 2]). This MUTATES the running/emulated system.

輸入參數op必填logname必填outputs必填

qsys_create_change_group

Create or extend a change group

Create a change group (or add Named Controls to an existing one) so you can poll for changes (ChangeGroup.AddControl).

輸入參數id必填controls必填

qsys_poll_change_group

Poll a change group

Poll a change group; returns the controls that changed since the last poll (ChangeGroup.Poll).

輸入參數id必填

qsys_change_group_add_component

Add component controls to a change group

Add a named component's controls to a change group so you can poll them for changes (ChangeGroup.AddComponentControl).

輸入參數id必填controls必填component必填

qsys_destroy_change_group

Destroy a change group

Destroy a change group, freeing its server-side state (ChangeGroup.Destroy).

輸入參數id必填

qsys_change_group_remove

Remove controls from a change group

Remove Named Controls from a change group, leaving the group in place (ChangeGroup.Remove). Returns any unknown control names.

輸入參數id必填controls必填

qsys_change_group_clear

Clear a change group

Remove all controls from a change group without destroying it (ChangeGroup.Clear).

輸入參數id必填

qsys_change_group_invalidate

Invalidate a change group

Invalidate a change group so the next poll resends every watched control, not just the changes (ChangeGroup.Invalidate). Handy after a reconnect to force a full snapshot.

輸入參數id必填

qsys_disconnect

Disconnect from Q-SYS

Close the QRC connection to the Core/emulator. A later qsys_connect is required before other tools.

無需輸入參數。

版本歷史

2
  1. v0.6.1最新Oct 29, 2026
  2. v0.6.0Sep 16, 2026

評分

已滿足適用檢查項的 90%

該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分
  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。

  • 已列出工具必需15 分
  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分