Q-SYS MCP

qsys-tools

QSC Q-SYS オーディオ／ビデオシステム向けのオープンソースツールです。シェル、コード、AI エージェントから Core を制御でき、Mac で Q-SYS Designer をネイティブに実行できます。

すべての Q-SYS Core と、エミュレートモードの Q-SYS Designer は、QSC が公開している QRC プロトコル（TCP ポート 1710 経由の JSON-RPC 2.0）を提供しています。これは Crestron／AMX の統合で使用されるものと同じ外部制御インターフェースです。このツール群はネイティブに対応しています。QSC のコードは不要で、SDK も不要です。開発にハードウェアも必要ありません。

パッケージ	内容
qsys-cli	CLI（コマンド：qsys）— ステータス、コンポーネント一覧、ランプ付きのコントロール取得／設定、ライブ監視、スナップショット
qsys-qrc	TypeScript QRC クライアント — ワイヤーフレーミング、変更グループ、キープアライブ、透過的な自動再接続、型付きプロトコル API
qsys-mcp	MCP サーバー（MCP Registry の io.github.reowens/qsys-mcp）— AI エージェントが稼働中の Q-SYS システムを調査・操作できる 18 個のツール
qsys-mac	npm ブートストラッパー（コマンド：qsys-mac）— 署名済みの Q-SYS Mac Installer DMG をダウンロードして検証し、ヘルパーに処理を委任します
qsys-mac-installer	macOS 用 Q-SYS Designer — 署名・公証済みの BYO インストーラーラッパーアプリと DMG ソース

クイックスタート — シェル

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

npm i -g qsys-cli でコマンドをグローバルにインストールします（バイナリ名は qsys です）。 スクリプトから使用する場合は、すべてのコマンドで --json を指定できます。watch は JSON 行を出力します。

クイックスタート — AI エージェント（MCP）

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

または、任意の MCP クライアントの設定に追加します。

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

その後、エージェントに Core（または Designer エミュレーター）への接続を依頼すると、メーターの読み取り、ミュートの切り替え、ゲインのランプ変更、コントロールの変更監視、スナップショットの呼び出しができます。Core の再起動後も自動再接続します。詳しくは packages/qsys-mcp をご覧ください。

MCP Registry に対応した MCP クライアントでは、io.github.reowens/qsys-mcp として検索できます。

クイックスタート — 独自コード

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

変更グループ（ポーリングベースの監視）、コンポーネントアクセス、スナップショット、ログオンは、すべて型付きヘルパーで利用できます。詳しくは packages/qsys-qrc をご覧ください。

Mac 上の Q-SYS Designer

ほとんどのユーザーには、署名済みの DMG インストーラーアプリをお勧めします。一度実行すると Q-SYS Designer.app が作成されます。その後、インストーラーアプリをゴミ箱に入れるか、Launch、Reinstall、Remove 用の小さなマネージャーとして手元に残しておけます。インストール済みの Designer アプリと Application Support のデータは、インストーラーアプリとは独立しています。

DMG を直接使う場合：

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

または npm ブートストラッパーを使用します：

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

署名済みの Q-SYS Mac Installer DMG をダウンロードして検証し、マウントした後、同梱のヘルパーを実行します。npm パッケージには Q-SYS Designer やアプリのペイロードは含まれていません。ご自身で Designer インストーラーを無料でダウンロードしてご用意ください（BYO — QSC のものは再配布していません）。

読み取り専用のサポート診断を実行するには、次のコマンドを使います：

npx qsys-mac doctor

現在の macOS の前提条件は Rosetta 2 です。署名済み DMG には Wine、.NET、7z、アイコンツール、msiinfo、ネイティブヘルパーバイナリが同梱されています。通常のセットアップに Homebrew やホスト側の Python は必要ありません。

GUI インストーラーアプリをお使いの場合は、Homebrew でインストールできます：

brew tap reowens/qsys
brew trust reowens/qsys
brew install --cask qsys-mac-installer
open -a "Q-SYS Mac Installer"

現在の Homebrew では、サードパーティの cask tap に brew trust が必要です。

署名済みインストーラーのソースは packages/qsys-mac-installer にあります。Wine と .NET を Application Support にセットアップし、Dock／Finder／メニューバーで普通のアプリとして使えるようにします。現在の署名済み DMG は qsys-mac-installer 0.1.4 です。

おまけ：Designer の Emulate mode は 127.0.0.1:1710 で QRC を提供するため、上記のすべてのツールをハードウェアなしで使用できます。このリポジトリのツールも、これを使って検証されています。

ハードウェアがありませんか？

Emulate mode で実行中の Q-SYS Designer に、任意のツールを接続してください（--host 127.0.0.1）。知っておくとよいプロトコル上の事実が 2 つあります。QRC には名前付きコントロールやスナップショットバンクを列挙するメソッドがないため、名前はデザインから取得する必要があります。また、Component.GetComponents が返すのは、スクリプトアクセスが有効になっているコンポーネントのみです。

開発

これは pnpm ワークスペースです（Node 22.13 以降。pnpm は packageManager フィールドを介して 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

e2e スイート（QRC 統合、モックを使った MCP のエンドツーエンド、透過的な再接続／AutoPoll 再生のリグレッション）は、リポジトリ内のデザイン駆動型 Q-SYS Core モックである qsys-mock-core に対して実行されます。そのため、pnpm test ではハードウェアなしでプロトコル全体をテストできます。より詳細な適合性テスト（Designer で検証したレンダリング、ランプ／メーター、および実際の Q-SYS デザインのライブラリ）には、別の、より機能が充実したエミュレーターを使用します。

qsys-mac-installer は Xcode で個別にビルドします。詳細は packages/qsys-mac-installer を参照してください（署名／公証のパイプラインは scripts/package.sh を参照）。

メンテナー向けのリリース手順は RELEASE.md に記載されています。

このソースチェックアウトから作業する場合は、ローカルのワークスペースパッケージと公開済みパッケージが混同されないよう、npx qsys-mac ではなくワークスペースのスクリプトを使用してください：

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

ライセンス

元の qsys-tools ソースコードは、QRC パッケージ、qsys-mac npm ブートストラッパー、qsys-mac-installer ラッパーアプリを含め、MIT ライセンスです。

署名済み macOS インストーラー DMG は、Wine、.NET、p7zip、icoutils、msiinfo、およびそれらのランタイムライブラリなど、再配布可能なサードパーティコンポーネントを同梱するため、複数のライセンスが適用されるバイナリ配布物です。これらのコンポーネントは、それぞれ独自のライセンスと通知の対象です。詳細は packages/qsys-mac-installer/THIRD-PARTY-NOTICES.md を参照してください。

各パッケージには独自の LICENSE ファイルが含まれています。

免責事項

これは独立したオープンソースプロジェクトであり、QSC, LLC とは提携、承認、後援のいずれの関係もありません。「Q-SYS」および「Q-SYS Designer」は QSC, LLC の商標であり、指示的な意味で使用しています。これらのツールは公開されている QRC プロトコルを使用し、QSC のコードは含まれていません。