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 on your Mac or Ubuntu desktop.

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 Example-Design (code a1B2c3D4e5F6) 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.9

Or use the npm bootstrapper:

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:

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

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:

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

npx qsys-linux doctor npx 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).

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 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:

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