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"
      }
    }
  }
}

Replace /absolute/path/to/MCP3.0/index.js with the actual path to your index.js file. Replace 192.168.50.150 with your Q-SYS Core IP address.

Testing

Manual testing checklist:

1. Connect to Q-SYS Core
2. Verify auto-reconnection (disconnect/reconnect network)
3. Discover components
4. Get/set control values
5. Test protected controls
6. Verify batch operations
7. Monitor memory usage

Agent Prompts

See agent-mcp3-prompts.md for example system prompts for:

• AV Room Controller Assistant
• Audio System Troubleshooting Agent
• Event Production Coordinator

License

MIT