Q-SYS MCP

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 natively on your Mac.

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.

Quick start — shell

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

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)

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

or in any MCP client config:

{
  "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

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();

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:

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

Or use the npm bootstrapper:

npx qsys-mac install "/path/to/Q-SYS Designer Installer 10.4.0.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:

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:

brew tap reowens/qsys
brew trust reowens/qsys
brew install --cask qsys-mac-installer
open -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.4.

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.

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).

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

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, ramps/meters, and a library of real Q-SYS designs) 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:

pnpm run qsys-mac -- status
pnpm 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, 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.