OBS MCP

OBS MCP bietet MCP-Clients eine aktuelle, inspizierbare Schnittstelle zu OBS Studio. Es stellt 155 Werkzeuge für Szenen, Quellen, Audio, Übergänge, Filter, Aufnahme, Streaming, Canvases und den Rest der OBS-WebSocket-v5-Anfrageoberfläche bereit.

Der Server ist gegen MCP 2026-07-28 gebaut und akzeptiert weiterhin Legacy-Clients aus der 2025-Ära. Die MCP-Erkennung bleibt verfügbar, wenn OBS geschlossen ist, und der Server verbindet sich im Hintergrund neu, sobald OBS zurückkehrt.

So funktioniert es

MCP client  <-- stdio -->  OBS MCP  <-- WebSocket v5 -->  OBS Studio

OBS MCP läuft als separater Node.js-Prozess. Es patcht OBS nicht und benötigt kein OBS-Plugin; es nutzt den in OBS Studio integrierten WebSocket-Server. MCP übernimmt die Werkzeugerkennung, Schemas, Ergebnisse und Genehmigungshinweise. OBS WebSocket verwaltet den Live-Zustand der Anwendung.

Related MCP server: obs-mcp-server

Was abgedeckt ist

• Alle 147 Anfragetypen des OBS-WebSocket-Protokolls in der Revision, die vom aktuellen OBS-Studio-Quellbaum festgelegt wird

• Explizite read-only-, destruktive, idempotente und Open-World-Anmerkungen für jedes Werkzeug

• Laufzeit-Fähigkeitsprüfungen gegen die vom verbundenen OBS-Instanz beworbenen Anfragen

• Protokollprüfung über obs-describe-request

• Ein generischer obs-call-request-Notausgang, begrenzt auf Anfragen im gebündelten OBS-Protokoll und als destruktiv für die Client-Freigabe markiert

• Ein reproduzierbarer .mcpb-Build, dessen Werkzeuginventar über MCP statt über private SDK-Interna generiert wird

Die expliziten Werkzeuge bleiben die normale Schnittstelle. Das generische Anfragewerkzeug ist dafür da, dass eine neu hinzugefügte OBS-Operation verwendet werden kann, bevor sie einen ergonomischeren Wrapper erhält.

Anforderungen

• Node.js 20.19 oder neuer

• OBS Studio 28 oder neuer mit aktiviertem WebSocket-Server

• Ein MCP-Client, der MCP 2026-07-28 oder das kompatible Legacy-Protokoll unterstützt

OBS enthält WebSocket v5. Aktivieren Sie es unter Werkzeuge > WebSocket-Server-Einstellungen. Neuere OBS-Anfragen sind nur verfügbar, wenn die verbundene Version sie bewirbt; nicht unterstützte Aufrufe geben eine beschreibende Fehlermeldung zurück.

Installation aus dem Quellcode

Dieses unabhängige Repository hat noch keine eigene npm-Veröffentlichung. Bis dahin führen Sie es aus einem lokalen Checkout aus:

git clone https://github.com/Tom-R-Main/OBS-MCP.git
cd OBS-MCP
npm ci
npm run check

Richten Sie dann Ihren MCP-Client auf den gebauten Einstiegspunkt aus:

{
  "mcpServers": {
    "obs": {
      "command": "node",
      "args": ["/absolute/path/to/OBS-MCP/build/index.js"],
      "env": {
        "OBS_WEBSOCKET_PASSWORD": "<password-from-obs>"
      }
    }
  }
}

Wenn OBS eine nicht standardmäßige Adresse verwendet, fügen Sie OBS_WEBSOCKET_URL zum Umgebungsblock hinzu.

Verbindung überprüfen

Öffnen Sie OBS, starten Sie eine neue Agent-Sitzung und fragen Sie:

Überprüfen Sie die OBS-Verbindung. Melden Sie die OBS-Version, die aktuelle Szene, den Streaming-Status und den Aufnahmestatus. Ändern Sie nichts.

Der Client sollte nur read-only-Werkzeuge anfordern und Live-Werte von OBS zurückgeben. Wenn die Werkzeugerkennung funktioniert, der Prompt aber meldet, dass OBS getrennt ist, lassen Sie den MCP-Server laufen und starten Sie OBS; die Wiederverbindung erfolgt im Hintergrund.

Das MCPB-Paket installieren

Erstellen Sie das Desktop-Paket lokal:

npm run pack

Der Befehl baut den Server neu, liest die öffentliche Werkzeugliste über MCP, installiert nur Produktionsabhängigkeiten in einem isolierten Staging-Verzeichnis, validiert das Manifest und schreibt:

dist/obs-studio.mcpb

Öffnen Sie diese Datei in einem MCPB-kompatiblen Desktop-Client. Das Paket fragt nach der OBS-WebSocket-URL und dem Passwort.

Konfiguration

Der Server gibt das Passwort niemals aus. Verbindungs- und Protokolldiagnosen werden nach stderr geschrieben, sodass stdout für MCP-Nachrichten reserviert bleibt.

Werkzeugoberfläche

Die 155 Werkzeuge sind um das OBS-Protokoll organisiert und nicht um einen kleineren, meinungsbildenden Workflow:

• Serverstatus, Versionsinformationen, Statistiken, Hotkeys und Studio-Modus

• Szenen, Gruppen, Quellen, Filter und Szenenelemente

• Eingabeeinstellungen, Audio, Lautstärke, Stummschaltung, Mediensteuerung und Deinterlacing

• Aufnahme, Streaming, Replay-Puffer, virtuelle Kamera und Ausgabeeinstellungen

• Übergänge, Übergangsüberschreibungen, der Übergangs-Cursor und der T-Bar

• Canvases, Screenshots, Profile, Szenensammlungen und persistente Daten

• Protokollbeschreibung und der abgesicherte generische Anfrage-Notausgang

Die Werkzeugerkennung funktioniert ohne OBS-Verbindung. Aufrufe, die OBS benötigen, geben einen MCP-Fehler zurück, bis die WebSocket-Verbindung bereit ist.

Wo es passt

OBS MCP eignet sich gut für operative Arbeiten, die bereits ein klares Ergebnis haben: eine Szenensammlung inspizieren, Quellen erstellen oder anordnen, den Audiostatus ändern, Szenen wechseln, Screenshots aufnehmen, den Ausgabestatus prüfen oder ein wiederholbares Aufnahme-Setup durchführen.

Es ersetzt nicht das visuelle oder auditive Urteilsvermögen. Bildausschnitt, Farbe, Übergangstiming, Audiobalance und die Entscheidung, live zu gehen, brauchen weiterhin eine Person, die das Ergebnis sieht und hört.

Sicherheit und Genehmigungen

Jedes Werkzeug veröffentlicht alle vier MCP-Verhaltenshinweise. Read-only-Inspektion ist von Zustandsänderungen getrennt, und Aktionen mit größeren Konsequenzen sind als destruktiv oder Open-World markiert, wo dies angemessen ist.

Achten Sie besonders auf Genehmigungen für Werkzeuge, die:

• Streaming, Aufnahme, virtuelle Kamera, Replay-Puffer oder einen anderen Ausgang starten oder stoppen

• Profile oder Szenensammlungen wechseln

• Hotkeys auslösen oder mit OBS-UI-Elementen interagieren

• Anbieteranfragen aufrufen

• Dateien speichern oder den generischen obs-call-request-Notausgang verwenden

obs-call-request akzeptiert nur Anfragetypen im gebündelten OBS-Protokoll, aber seine Nutzlast ist absichtlich generisch. Es ist immer als destruktiv und Open-World markiert, damit ein Client eine unbekannte Operation nicht stillschweigend als sicher behandelt.

Fehlerbehebung

Werkzeuge erscheinen, aber OBS-Aufrufe schlagen fehl: Stellen Sie sicher, dass OBS geöffnet und sein WebSocket-Server aktiviert ist. Der MCP-Prozess bleibt verfügbar, während er die Verbindung erneut versucht.

Die Authentifizierung schlägt fehl: Kopieren Sie das Passwort aus Werkzeuge > WebSocket-Server-Einstellungen in OBS_WEBSOCKET_PASSWORD und starten Sie dann den MCP-Serverprozess neu.

Der Agent kann die Werkzeuge nicht sehen: Starten Sie die Agent-Sitzung oder den MCP-Host neu, damit er eine frische stdio-Verbindung erstellt und die Werkzeugliste neu lädt.

Eine Anfrage wird nicht unterstützt: Die verbundene OBS-Build hat diese WebSocket-Anfrage nicht beworben. Verwenden Sie eine Operation, die von dieser Version unterstützt wird, oder aktualisieren Sie OBS.

Der Prozess beendet sich oder gibt Protokollfehler aus: Prüfen Sie stderr. stdout ist für MCP-Datenverkehr reserviert und sollte nicht in normale Anwendungsprotokolle umgeleitet werden.

Entwicklung

npm ci
npm run build
npm test
npm run validate:manifest

Führen Sie das vollständige lokale Gate aus mit:

npm run check

Die Tests decken den OBS-WebSocket-Handshake und die Anforderungskorrelation, gleichzeitige Verbindungsversuche, Fähigkeitsprüfungen, exakte OBS-Anforderungsparität, deterministische Werkzeugerkennung, Anmerkungen sowie sowohl Legacy- als auch MCP-2026-07-28-Verhandlung ab.

TypeScript-Richtlinie

Die Anwendung wird mit TypeScript 7.0.2 gebaut und importiert die TypeScript-Compiler-API nicht. Wenn ein zukünftiger Generator, Linter oder ein Build-Werkzeug programmatischen Compiler-Zugriff benötigt, behalten Sie dieses Werkzeug auf TypeScript 6, während der Anwendungs-Compiler auf TypeScript 7 bleibt. TypeScript 7.0 liefert keine programmatische API; Microsoft dokumentiert das nebeneinander laufende TypeScript-6-Kompatibilitätspaket in den TypeScript-7.0-Versionshinweisen.

Protokoll-Baselines

Diese Revision wurde gegen diese exakten Quellen geprüft:

• MCP-Spezifikation: cbd57657

• MCP-TypeScript-Server- und -Client-SDKs: 2.0.0

• OBS Studio: 0043697f

• OBS WebSocket: 1ef34bf4, die Revision, die von diesem OBS-Studio-Checkout festgelegt wird

Die generierten Protokolldateien liegen unter docs/. Tests vergleichen jede von den Werkzeugmodulen verwendete Anfrage mit dem gebündelten Protokoll, sodass veraltete Anforderungsnamen und fehlende Wrapper lokal fehlschlagen.

Projektgeschichte

Dieses Projekt begann mit Roy Shilkrots obs-mcp, einschließlich Upstream-Arbeit von Zeke Sikelianos. Es bewahrt auch Jag-k's MCPB-Paketierung und die registerTool-Migrationsarbeit auf. Ihre ursprünglichen Commits und Urheberschaften bleiben in der Git-Historie erhalten.

Lizenz

OBS MCP ist unter GPL-2.0-only lizenziert. Veröffentlichte npm- und MCPB-Pakete enthalten den entsprechenden TypeScript-Quellcode und die Build-Skripte. Siehe LICENSE und NOTICE.md.