Q-SYS MCP

io.github.reowensPublished by GitHub account reowensv0.6.1Updated Nov 6, 2026

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

VerifiedSTDIODesktop onlyCloud & InfrastructureMedia & Design

Overview

AI-generated overview

Lets an AI assistant connect to a QSC Q-SYS Core or Designer emulator over QRC and inspect, adjust and monitor audio/video controls.

What you can do
  • Connect to a Core or Designer emulator and read engine status
  • List components and read their controls and current values
  • Set named controls and component values, with optional ramps
  • Recall and save snapshots, and drive mixer crosspoints, inputs, outputs and cues
  • Start, stop and cancel Loop Player audio playback
  • Create, poll, trim and destroy change groups to watch controls for changes
When to use it
Useful when you work with Q-SYS audio/video systems and want an assistant to read meters and control values, adjust gains and mutes, recall snapshots, or watch controls for changes — including against Designer in Emulate mode without hardware.
Requirements
Runs locally as an npm package (qsys-mcp) via npx, so Node.js is needed. Network access to a Q-SYS Core or to Q-SYS Designer in Emulate mode on TCP port 1710; the host and port are passed to the connect tool. No API keys or environment variables are declared.
Before you install
Many tools change the live system: setting controls, mixer gains/mutes, snapshot recall and Loop Player playback all mutate the running or emulated design, and saving a snapshot overwrites the stored one. Point it at an emulator first. QRC cannot enumerate named controls or snapshot banks, and only components with script access enabled are visible.

Installation

In SourceWeft

  1. Open Q-SYS MCP in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

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.

Source: README.md at commit 0057e21

Tools

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.

Parametershostportuserpasswordreconnectallow_live_writes

qsys_status

Q-SYS engine status

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

Takes no parameters.

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.

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

Parametersnamerequiredfilternames_only

qsys_get_control

Get control values

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

Parametersnamesrequired

qsys_get_component

Get specific component control values

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

Parametersnamerequiredcontrolsrequired

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.

Parametersnamerequiredrampvaluerequired

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.

Parametersnamerequiredcontrolsrequired

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.

Parametersbankrequiredrampnumberrequired

qsys_save_snapshot

Save a snapshot

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

Parametersbankrequirednumberrequired

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.

Parametersoprequirednamerequiredrampvaluerequiredinputsrequiredoutputsrequired

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.

Parametersoprequirednamerequiredrampvaluerequiredinputsrequired

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.

Parametersoprequirednamerequiredrampvaluerequiredoutputsrequired

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.

Parametersoprequiredcuesrequirednamerequiredrampvaluerequired

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.

Parametersoprequiredcuesrequirednamerequiredvaluerequiredinputsrequired

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.

ParameterslogloopnamerequiredseekfilesrequiredrefIdstartTime

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.

Parametersoprequiredlognamerequiredoutputsrequired

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

Parametersidrequiredcontrolsrequired

qsys_poll_change_group

Poll a change group

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

Parametersidrequired

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

Parametersidrequiredcontrolsrequiredcomponentrequired

qsys_destroy_change_group

Destroy a change group

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

Parametersidrequired

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.

Parametersidrequiredcontrolsrequired

qsys_change_group_clear

Clear a change group

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

Parametersidrequired

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.

Parametersidrequired

qsys_disconnect

Disconnect from Q-SYS

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

Takes no parameters.

Version history

2
  1. v0.6.1LatestOct 29, 2026
  2. v0.6.0Sep 16, 2026

Score

90% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts
  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts