MCP 服务器

Q-SYS MCP Server

Enables control and monitoring of Q-SYS audio/video systems through WebSocket connection. Provides tools for discovering components, reading/setting control values, and managing system status with built-in protection for critical controls.

README

Q-SYS MCP3.0 Server

Ultra-minimal MCP server for Q-SYS control. ~400 lines, 3 dependencies, 5 tools.

Quick Start

# Install
npm install

# Run with environment variable
QSYS_HOST=192.168.1.100 npm start

# Run with debug logging
npm run dev

Configuration

Environment Variables

QSYS_HOST=192.168.1.100    # Q-SYS Core IP address
QSYS_PORT=443               # WebSocket port (default: 443)
QSYS_AUTO_CONNECT=true      # Auto-connect on startup
QSYS_MCP_DEBUG=true         # Enable debug logging
QSYS_POLLING_INTERVAL=350   # Control polling interval in ms

Config File

The server saves successful connections to ~/.qsys-mcp/last-connection.json and auto-connects on next startup.

Tools

qsys_connect

Connect to Q-SYS Core with auto-reconnection.

{
  "host": "192.168.1.100",
  "port": 443,
  "secure": true,
  "pollingInterval": 350
}

qsys_discover

List components and their controls.

{
  "component": "Gain.*",     // Optional regex filter
  "includeControls": true    // Include control details
}

qsys_get

Read control values.

{
  "controls": ["Gain_1.gain", "Gain_1.mute"]
}

qsys_set

Update control values with protection.

{
  "controls": [
    {
      "path": "Gain_1.gain",
      "value": -10,
      "force": false    // Required for protected controls
    }
  ]
}

qsys_status

Get connection and system status.

{
  "detailed": false    // Include component inventory
}

Protected Controls

These patterns require force: true to modify:

Master.* - System-wide master controls
Emergency.* - Emergency systems
*.power - Power controls
SystemMute - Venue-wide mute

Features

Auto-reconnection: Exponential backoff (1s, 2s, 4s, 8s, 16s)
Global cache: 1-second discovery cache, clears on reconnect
Parallel operations: Batch updates execute simultaneously
Type validation: Enforces correct types for Boolean, Float, Integer
Range validation: Respects ValueMin/ValueMax limits
Helpful errors: Suggests available components/controls when not found

Performance

Tool response: <10ms overhead
Memory usage: <50MB
Startup time: <500ms
Connection time: <1 second
Batch operations: Parallel execution

Claude Desktop Configuration

Add to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Option 1: Minimal Configuration (Manual Connect)

Use this for flexibility with multiple Q-SYS systems:

{
  "mcpServers": {
    "qsys-mcp3": {
      "command": "node",
      "args": ["/absolute/path/to/MCP3.0/index.js"]
    }
  }
}

With this config, you'll need to connect manually in Claude:

"Connect to Q-SYS Core at 192.168.50.150"

Option 2: Auto-Connect Configuration

Use this for dedicated single-system setups:

{
  "mcpServers": {
    "qsys-mcp3": {
      "command": "node",
      "args": ["/absolute/path/to/MCP3.0/index.js"],
      "env": {
        "QSYS_HOST": "192.168.50.150",
        "QSYS_PORT": "443",
        "QSYS_AUTO_CONNECT": "true",
        "QSYS_MCP_DEBUG": "false"
      }
    }
  }
}