QLab MCP Server

A Model Context Protocol server that lets an LLM (Claude Desktop, Claude Code, or any MCP client) control QLab live over OSC - query the workspace, list and search cues, start/stop/pause, create cues, set properties, and fire raw OSC or AppleScript.

Ask your assistant "what cues are running?", "create an audio cue numbered 5 and arm it", or "GO" and it drives QLab directly.

Tools

• Workspace: workspace_info, list_cues, search_cues
• Query: get_cue_info, get_running_cues, get_playback_position
• Playback: go, start_cue, stop_cue, pause_cue, resume_cue, reset_cue, panic, move_playback
• Authoring: create_cue, set_cue_property, arm_cue
• Escape hatches: send_osc (any raw OSC address + args), run_applescript (arbitrary AppleScript against the front workspace)

Requirements

• QLab 4 or 5 on macOS, with OSC enabled (QLab Settings > OSC; "Use OSC controls"). Default OSC ports are 53000 (send) / 53001 (receive).
• Python 3.10+ and the dependencies in requirements.txt (mcp, python-osc).

Install

git clone https://github.com/magichao326/qlab-mcp.git
cd qlab-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

Configure your MCP client

Claude Desktop (claude_desktop_config.json) or Claude Code (.mcp.json):

{
  "mcpServers": {
    "qlab": {
      "command": "/absolute/path/to/qlab-mcp/.venv/bin/python3",
      "args": ["/absolute/path/to/qlab-mcp/server.py"]
    }
  }
}

Configuration (environment variables)

Var	Default	Meaning
QLAB_HOST	127.0.0.1	Machine running QLab. 127.0.0.1 if same Mac.
QLAB_SEND_PORT	53000	QLab's OSC receive port.
QLAB_RECV_PORT	53001	Port this server listens on for replies.
QLAB_PASSCODE	(empty)	QLab OSC passcode, if you set one.

Notes

• Controlling a live show from an LLM is powerful and unattended tool-calls can fire real cues. Point it at a rehearsal/backup workspace first, and consider a QLab OSC passcode.
• search_cues walks the cue-list tree client-side (QLab has no native OSC search).

Disclaimer

Not affiliated with or endorsed by Figure 53. "QLab" is a trademark of Figure 53. Independent, community tooling, provided as-is.

License

MIT - see LICENSE.