PixDrive Studio MCP Setup - PixDrive Studio

PixDrive Studio bringt einen integrierten MCP-Server (Model Context Protocol) mit, über den du KI-Assistenten wie Claude Desktop, Cursor oder eigene Skripte deine Lichtshow steuern lassen kannst — Effekte starten, Parameter live ändern, Sequenzen abspielen, Lua-Skripte ausführen.

Der Server läuft lokal auf 127.0.0.1 und ist standardmäßig deaktiviert. Du aktivierst ihn manuell und kannst ihn mit einem Passwort absichern.

1. Was ist das MCP?

Model Context Protocol ist ein offener Standard, mit dem LLM-Clients Tools eines lokalen Programms aufrufen können. PixDrive Studio stellt ~20 Tools bereit (Effekte, Geräte, Sequenzer, Skripte). Ein Assistent kann damit z. B. sagen:

„Mach den Plasma-Effekt im Hintergrund langsam, leg darüber einen Audio-reaktiven Strobe.“

Und der Client setzt das in eine Reihe von Tool-Calls um.

2. Server aktivieren

Öffne Einstellungen (Zahnrad-Icon in der Toolbar)
Scrolle zum Abschnitt MCP Server
Schalter Server aktiv umlegen
App neu starten — der TCP-Listener wird nur beim Start gebunden

Nach dem Neustart steht der Server unter:

http://127.0.0.1:9847/mcp

Im Einstellungsdialog kannst du die URL mit einem Klick kopieren.

3. Passwort setzen (empfohlen)

Ohne Passwort akzeptiert der Server jede Verbindung von localhost. Das reicht für Single-User-Setups, aber sobald andere Prozesse auf der Maschine laufen (oder du der Maschine nicht 100 % traust), solltest du ein Passwort vergeben:

Einstellungen → MCP Server → Passwort
Passwort eingeben, Speichern klicken
Sofort aktiv — kein Neustart nötig

Das Passwort wird niemals im Klartext gespeichert — PixDrive Studio legt nur einen gesalzenen SHA-256-Hash in mcp.json ab. Vergisst du es, setze einfach ein neues.

Clients senden das Passwort als Bearer-Token im HTTP-Header:

Authorization: Bearer <dein-passwort>

4. Client-Konfiguration

Claude Desktop

Öffne die Config-Datei:

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

Eintrag hinzufügen:

{
  "mcpServers": {
    "pixdrive": {
      "transport": {
        "type": "streamableHttp",
        "url": "http://127.0.0.1:9847/mcp",
        "headers": {
          "Authorization": "Bearer DEIN-PASSWORT"
        }
      }
    }
  }
}

Ohne Passwort lässt du den headers-Block weg. Claude Desktop neu starten — PixDrive erscheint in der Tool-Liste.

Cursor / Continue / andere MCP-Clients

Die meisten Clients erwarten ebenfalls eine HTTP-MCP-URL plus optionale Headers. Tragen ein:

URL: http://127.0.0.1:9847/mcp
Header: Authorization: Bearer DEIN-PASSWORT

Konkrete Pfade variieren — siehe Doku des jeweiligen Tools.

Generischer HTTP-Test

Schneller Verbindungstest mit curl:

curl -i -H "Authorization: Bearer DEIN-PASSWORT" \
     -H "Content-Type: application/json" \
     -X POST http://127.0.0.1:9847/mcp \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Antwort 200 OK → Verbindung steht. 401 Unauthorized → Passwort falsch oder fehlt.

5. Verfügbare Tools (Übersicht)

Bereich	Tools
Effekte	`list_effects`, `start_effect`, `stop_effect`, `set_parameter`, `get_effect_parameters`
Skripte	`start_script_effect`, `validate_script`, `get_script_guide`
Sequenzer	`play_sequence`, `pause_sequence`, `stop_sequence`, `set_sequence_position`
Geräte	`list_devices`, `add_device`, `remove_device`, `add_fixture`, `apply_device_config`

Vollständige Beschreibungen liefert der Server selbst via tools/list (Standard-MCP-Methode).

Tipp: Bevor ein Assistent ein Lua-Skript generiert, sollte er einmal get_script_guide aufrufen — das Tool liefert die komplette Skript-API.

6. Demo- und Trial-Versionen

Im Demo-Modus (keine Lizenz) startet der MCP-Server nicht. Eine gültige PixDrive-Studio-Lizenz ist Voraussetzung.

7. Sicherheits-Hinweise

Der Server bindet ausschließlich 127.0.0.1 — kein Remote-Zugriff über das Netzwerk.
Passwort-Vergleich läuft konstant-Zeit, gesalzen, pro Setzen neu salted.
Der Token-Header schützt vor lokalen Fremdprozessen. Er schützt nicht vor einem Angreifer, der bereits Code auf deinem Account ausführt.
Wenn du den Server nicht benutzt: deaktivieren.

8. Troubleshooting

„Connection refused“ im Client → Server nicht aktiviert, App nicht neu gestartet, oder Port 9847 von etwas anderem belegt. Prüfe das Log (Hilfe → View Logs) auf die Zeile MCP server started on … bzw. failed to bind port.

„401 Unauthorized“ → Passwort gesetzt, aber Client sendet falsches oder gar kein Authorization-Header. Passwort im Settings-Dialog neu setzen und in der Client-Config nachziehen.

„MCP server disabled via settings, not starting“ im Log → Schalter ist aus. Aktivieren und App neu starten.

Tools tauchen im Client nicht auf, aber Verbindung steht → Client unterstützt den MCP-tools/list-Aufruf nicht oder cached eine alte Liste. Client neu starten.