# QLab MCP Server

A [Model Context Protocol](https://modelcontextprotocol.io) server that lets an
LLM (Claude Desktop, Claude Code, or any MCP client) **control [QLab](https://qlab.app)
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

```bash
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`):

```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](LICENSE).