obs-control-mcp

An MCP server to inspect and safely control OBS Studio over obs-websocket v5 — built for people who let an AI assistant near the OBS they stream with.

• Read everything: version and performance stats, scenes, inputs and their settings, filters with their settings, stream/recording status, output paths, video settings.

• Change things only on purpose: every tool that changes OBS is a dry run unless you say otherwise, and a live guard refuses changes while OBS is streaming or recording unless you explicitly confirm.

• «¿Listo para grabar?» — a readiness check for the Source Record plugin.

• IRL: «¿listo para el IRL?» checks the wiring of an incoming phone/camera feed (Media Source, live and BRB scenes), and a BRB auto-switcher (NOALBS-style, with hysteresis) that runs on the command line, as a dry run until you say --apply.

• Scene timeline — a JSON-lines log of which scene was on program, and when, so you can cut clips from a VOD later.

• No secrets in logs or outputs — tested.

Leer en español

Safety design

Related MCP server: OBS MCP

Tools

Read (never change OBS)

Write (guarded: dry_run defaults to true; confirmLive=true required while live)

Source Record readiness check

check_source_record (or obs-control-mcp check on the command line) finds every source_record_filter and checks, for each one:

• the filter is enabled and its record mode (none / always / streaming / recording / streaming or recording / virtual camera), and whether it is writing a file right now;

• encoder, rate control and the QP/CQP/CRF actually in use (when the filter does not set it, the encoder's OBS default), or the bitrate;

• scaling and resolution, frame rate (divisor) against the canvas fps;

• file names: two filters writing to the same folder with the same format collide (they start in the same second); formats without date/time codes;

• output folder and container (mp4/mov are lost if OBS crashes; hybrid_mp4, mkv and fragmented formats are not);

• audio: own sound, another source (exists? muted?) or a mixer track; sources with no audio of their own (screen capture) give a silent file;

• filter order: masks, crops and keys above Source Record are baked into the file; below it they stay out;

• capture devices with «Deactivate when not showing»;

and globally: free disk (GetStats.availableDiskSpace, with an hours estimate when bitrates are known), render fps vs canvas fps, lagged frames, number of simultaneous encoders, and whether OBS is streaming/recording.

The verdict is ready, ready_with_warnings, not_ready or no_source_record_filters, with a Spanish one-liner (veredicto). The command line exits 0 / 1 / 2 accordingly (3 on connection errors).

IRL: readiness check and BRB auto-switcher

For IRL streams the phone or camera sends its feed to a relay and OBS at home reads it with a Media Source inside a live scene; a BRB («be right back») scene covers the dropouts. Default names, all configurable: live scene IRL, BRB scene Ahorita regreso, feed input Señal IRL.

check_irl (MCP) / obs-control-mcp check-irl [--live S] [--brb S] [--feed I] checks, read-only: both scenes exist and differ; the BRB scene shows something; the feed is a Media Source (ffmpeg_source), visible in the live scene and not in the BRB one; it reads a network input and which protocol (the URL itself is never reported: it names the relay and, with SRT, carries the passphrase); SRT without passphrase and plain RTMP are flagged; the reconnect delay; «Close file when inactive» (with it on, the Media Source is closed while BRB is on program, so the switcher could never see the feed come back); a Source Record filter on the feed (a clean copy, which is what clips are cut from); the stream service; render fps; free disk; and whether the feed is playing right now. Verdict and exit codes as check.

obs-control-mcp brb watches the feed and switches between the two scenes:

obs-control-mcp brb                 # dry run: logs what it would do, changes nothing
obs-control-mcp brb --apply         # switches for real
obs-control-mcp brb --help          # every option

• Signal: OBS's own media state (GetMediaInputStatus: playing or not) and, with --stats-url http://relay:9997 --stats-path irl, the bitrate read from a mediamtx control API (bytesReceived deltas), so a feed that still "plays" at 200 kbps counts as bad too.

• Hysteresis on both sides: bad for --down seconds (default 3) → BRB; good for --up seconds (default 5) → back; never two automatic switches within --dwell seconds (default 10); bitrate below --low (400 kbps) is bad, at or above --ok (1000 kbps) is good, in between nothing changes.

• It only ever moves between its two scenes. With any other scene on program it stands by. A BRB you selected by hand stays until you return (pass --return-from-manual-brb for NOALBS-like behaviour).

• --apply is the person's confirmation to act while live (that is the switcher's job); it still goes through the same guard as every write tool and is refused under OBS_READ_ONLY=1. The stats URL is treated as a secret (it may carry credentials) and never logged.

Scene timeline

When OBS_TIMELINE_FILE is set, the server subscribes to OBS events and appends one JSON object per line:

{"t":"2026-01-01T20:02:00.000Z","type":"event","event":"CurrentProgramSceneChanged","data":{"sceneName":"Main"}}

Recorded: program/preview scene changes, stream / recording / replay buffer / virtual camera state, scene item visibility (with the source name), filter and input creation, renames, enable state and settings changes (redacted), mutes. After every (re)connection it writes a snapshot of the current scene and outputs, including how long the stream has been running, so offsets stay on the stream's clock after a reconnect.

read_timeline turns it into scene segments (split where the stream/recording starts or stops) with streamOffsetSec — seconds into the stream, which is the VOD timestamp — time per scene, stream and recording sessions, and answers “what was live at …” (at) or “at second N of the stream” (atStreamOffsetSec).

Only one process records a given file (a pid lock). To record without an MCP client running, use obs-control-mcp timeline. The file grows by a few hundred lines per stream; rotate or delete it as you see fit — nothing else reads it.

Install

Requires Node.js ≥ 22.18 and OBS 28+ (obs-websocket 5 is built in: Tools → WebSocket Server Settings).

git clone https://github.com/rjla-developer/obs-control-mcp.git
cd obs-control-mcp
npm ci && npm run build

Configuration (environment only)

Claude Code

Keep the password out of the client's config: point the client at a small launcher that sets the variables, and let the server read the password file.

cat > ~/obs-control.sh <<'SH'
#!/usr/bin/env bash
export OBS_HOST=192.0.2.10 OBS_PORT=4455
export OBS_PASSWORD_FILE="$HOME/.config/obs-control/password"
export OBS_TIMELINE_FILE="$HOME/.local/share/obs-control/timeline.jsonl"
exec node /path/to/obs-control-mcp/dist/cli.js "$@"
SH
chmod 700 ~/obs-control.sh
claude mcp add obs-control -s user -- ~/obs-control.sh

Other MCP clients: run node dist/cli.js over stdio with the same variables.

Command line

obs-control-mcp            # MCP server on stdio
obs-control-mcp check      # Source Record readiness, JSON on stdout
obs-control-mcp check-irl  # IRL readiness, JSON on stdout
obs-control-mcp brb        # BRB auto-switcher, dry run (add --apply to switch)
obs-control-mcp timeline   # only record the timeline, until Ctrl-C

Development

npm ci
npm run lint && npm run typecheck && npm test
npm run check-secrets     # also runs as a pre-commit hook and in CI

Tests run against a fake obs-websocket v5 server (test/fakeObs.ts) that implements the real handshake (challenge/salt authentication) and the requests used here. Put your own LAN address, user name or host names in a git-ignored .forbidden-strings file (one per line) and the secret check will block them too.

License

MIT

En español

Servidor MCP para ver y controlar con cuidado OBS Studio por obs-websocket v5.

• Lee todo: versión y rendimiento, escenas, fuentes y sus ajustes, filtros y sus ajustes, estado de transmisión y grabación, carpetas de salida, video.

• Cambia solo a propósito: cada herramienta que cambia algo es un dry run (dry_run=true) hasta que se pide lo contrario, y mientras OBS transmite o graba se niega a cambiar nada si no va confirmLive=true. Antes de confirmar en vivo, hay que preguntarle a quien transmite.

• «¿Listo para grabar?»: check_source_record revisa cada filtro de Source Record — modo de grabación, codificador y calidad (CQP), escala, fps, nombres de archivo que chocan, carpeta y contenedor, de dónde sale el audio, si hay máscaras encima del filtro (se quedan en el archivo), cámaras con «Desactivar cuando no se muestra» y el espacio libre en disco — y da un veredicto: ready, ready_with_warnings o not_ready.

• IRL: check_irl revisa que OBS esté cableado para recibir la señal del teléfono o la cámara (escena en vivo, escena «Ahorita regreso», la Media Source con su protocolo —nunca la URL—, «cerrar cuando no se muestra», el Source Record de la señal limpia) y obs-control-mcp brb cambia solo a «Ahorita regreso» cuando la señal se cae y regresa cuando vuelve, con histéresis; sin --apply solo dice lo que haría.

• Línea de tiempo de escenas: con OBS_TIMELINE_FILE, apunta en un archivo JSON-lines qué escena estaba al aire y cuándo; read_timeline responde «¿qué se veía en el segundo 01:23:45 del directo?» para sacar clips del VOD.

• Ningún secreto sale del proceso: la contraseña se lee de un archivo (OBS_PASSWORD_FILE), nunca se escribe en el log, y las claves de transmisión, tokens y URLs de widgets se muestran como [redacted]. Las pruebas corren el proceso real con DEBUG=* y fallan si aparece la contraseña o una clave.

Instalación: npm ci && npm run build, y registrar en el cliente MCP un pequeño lanzador que ponga OBS_HOST, OBS_PORT y OBS_PASSWORD_FILE (ver arriba). Con OBS_READ_ONLY=1 solo se registran las herramientas de lectura.