Q-Sys MCP服务器
MCP服务器，用于控制Claude或Cursor的QSC Q-Sys核心。支持实时音频控制、快照管理、组件检查和QRC和ECP上的Lua脚本。
另请参见： Q-SYS-MCP-WEBUI -相同内核的浏览器UI。
它的作用
- 在跑步设计中调整推子、静音、均衡器、动态、矩阵交叉点
- 一次连接到多个核心
- 列出、加载和保存快照
- 读写组件控件
- 在Core上运行Lua脚本
- QRC（JSON-RPC，端口1710），ECP（文本，端口1702）作为回退
需求
- Node.js 20+
- 网络上的Q-Sys Designer 10.x核心
- 克劳德桌面 或任何MCP兼容主机
Q-Sys设计器设置
脚本访问（组件工具需要）
如果组件在Q-Sys Designer中启用了脚本访问，则MCP只能看到这些组件。没有它， qsys_list_components 即使Core可访问，也不会返回任何内容。
- 在Q-Sys Designer中打开您的设计
- 选择要控制的块（全部按Ctrl+A）
- 在“属性”面板中，将“脚本访问”设置为“外部”（或“全部”）
- 保存并推送设计
命名控件（可选）
如果使用脚本访问，则不需要Q-Sys Designer的“外部控件”窗格中的命名控件。如果您想要特定控件的短别名或需要基于ECP的集成，它们很有用。
安装
npm install
npm run build配置
添加到您的 claude_desktop_config.json （克劳德桌面）或 .cursor/mcp.json （光标）：
{
"mcpServers": {
"qsys": {
"command": "node",
"args": ["/path/to/q-sys-mcp/dist/index.js"],
"env": {
"QSYS_CORES": "sfo-allhands=10.1.1.100,nyc-display=10.2.1.100"
}
}
}
}QSYS_CORES格式
alias=host[:qrcPort[:ecpPort[:wsPort]]], ...省略端口段以使用默认值（TCP QRC:1710，ECP:1702）。添加a wsPort 将该Core切换到WebSocket QRC（QRWC）。
# Single Core, TCP QRC
QSYS_CORES=sfo=10.1.1.100
# Multiple Cores
QSYS_CORES=sfo=10.1.1.100,nyc=10.2.1.100,toronto=10.3.1.100
# WebSocket QRC on port 443
QSYS_CORES=sfo=10.1.1.100:::443
# Custom ports
QSYS_CORES=lab=192.168.1.50:1710:1702TCP QRC与WebSocket QRC
| TCP QRC | WebSocket QRC | |
|---|---|---|
| 端口 | 1710 | 443（默认） |
| 协议 | 基于TCP的JSON-RPC | 基于wss的JSON-RPC:// |
| qsys_list_components | 所有组件 | 仅限脚本访问组件 |
| qsys_run_lua | 是 | 否 |
| 证书 | n/a | 自签名（自动接受） |
WebSocket模式要求在核心管理器的“网络”>“服务”下启用WebSocket功能。
工具
| 工具 | 说明 |
|---|---|
qsys_list_cores | 列出配置的核心和连接状态 |
qsys_core_status | 获取核心名称、设计、运行状态 |
qsys_get_control | 获取命名控件值 |
qsys_set_control | 设置命名控制值 |
qsys_get_controls | 一次获取多个命名控件 |
qsys_list_components | 列出运行设计中的所有组件 |
qsys_get_component_controls | 获取组件的所有控件 |
qsys_set_component_controls | 在组件上设置一个或多个控件 |
qsys_list_snapshots | 列出可用快照 |
qsys_load_snapshot | 加载快照 |
qsys_save_snapshot | 将当前状态保存到快照 |
qsys_run_lua | 在Core上运行Lua代码 |
qsys_create_change_group | 创建用于轮询的更改组 |
qsys_poll_change_group | 轮询更改组以获取更新值 |
qsys_destroy_change_group | 清理变更组 |
示例提示
"Raise the main PA fader on sfo-allhands by 3dB"
"Mute all wireless mic channels on the NYC Core"
"Load the Pre-show snapshot on sfo-allhands"
"What components are in the running design on the Toronto Core?"
"Set the EQ high-shelf on the lectern mic to +2dB at 10kHz"建筑
Claude MCP Server ConnectionManager
|
+---------+-----------+
| |
QrcClient / WsQrcClient EcpClient
(JSON-RPC, TCP 1710 (Text Protocol
or wss:// port 443) TCP 1702)
| |
+-----> Q-Sys Core(s)连接是懒惰的——内核在第一次工具调用时连接，而不是在启动时。所有套接字管理都经过 ConnectionManager；工具代码从不直接打开套接字。
发展
npm run build # compile TypeScript
npm run dev # watch mode
node dist/index.js # run the server安全
qsys_run_lua 在Core上运行任意Lua。仅将此服务器暴露给受信任的MCP客户端。请注意，Lua执行需要TCP QRC（端口1710），在WebSocket QRC上不可用。