A server for the Model Context Protocol (MCP) that enables control of QSC Q-SYS systems over QRC from AI agents or Claude. This MCP server integrates with Q-SYS tooling to expose model-context interactions and command routing for automated agents.

🛠️ Key Features

Implements Model Context Protocol (MCP) to communicate with Q-SYS QRC
Enables AI agents and Claude to control Q-SYS Q-SYS systems
TypeScript/Node.js based tooling for cross-platform usage
Open-source tooling to operate QSC Q-SYS from CLI or code
Readme excerpt indicates integration with qsys-qrc and related tools

🚀 Use Cases

Automate Q-SYS room and DSP control via AI agents
Integrate MCP-driven workflows with Q-SYS QRC in macOS environments
Scripted control of Core systems from shells or applications

⚡ Developer Benefits

Grounding in MCP server data and Q-SYS tooling
Type-safe, Node.js/TypeScript implementation
Reusable tooling for CLI and programmatic control

⚠️ Limitations

Source data limited to description and readme excerpt; exact API surface not fully enumerated
Specific MCP command set and QoS guarantees not detailed in available data

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.

Package	What it is
`qsys-cli`	CLI (command: `qsys`) — status, component inventory, get/set controls with ramps, live watch, snapshots
`qsys-qrc`	TypeScript QRC client — wire framing, change groups, keepalive, transparent auto-reconnect, typed protocol surface
`qsys-mcp`	MCP server (`io.github.reowens/qsys-mcp` in the MCP Registry) — 18 tools that let an AI agent inspect and drive a live Q-SYS system
`qsys-mac`	npm bootstrapper (command: `qsys-mac`) — downloads/verifies the signed Q-SYS Mac Installer DMG and delegates to its helper
`qsys-mac-installer`	Q-SYS Designer for macOS — signed/notarized BYO-installer wrapper app + DMG source

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

code

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

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

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.

Q-SYS MCP