obs-mcp — OBS Studio control for AI assistants via MCP
obs-mcp is a Rust Model Context Protocol (MCP) server that controls OBS Studio over the OBS WebSocket v5 protocol. It gives AI assistants full command of a running OBS instance: switching scenes, creating sources, tuning audio, driving streams and recordings, managing transitions and studio mode, and more — all through plain tool calls.
The server is a faithful OBS WebSocket v5 client in Rust, validated against the official obs-websocket protocol specification and a real OBS 32 instance. The tool surface mirrors the public OBS WebSocket v5 protocol, so anything the protocol can do, the assistant can do.
Features
- 157 declarative tools covering the OBS WebSocket v5 request surface: scenes, scene items, inputs, filters, media inputs, transitions, outputs, streaming, recording, replay buffer, virtual cam, studio mode, hotkeys, profile and scene-collection management, video settings, and UI dialogs — including the OBS 32 additions (canvases, groups, scene-item per-property accessors, input audio tracks and deinterlace, private settings, TBar).
- OBS WebSocket v5 client in Rust: Hello/Identify handshake, SHA-256 challenge authentication, correlated request/response with timeouts, and automatic reconnection when OBS restarts.
- Table-driven tool registration: every tool is a thin, declarative wrapper around one protocol request, generated by a script from the reference projects — easy to audit and extend.
- Protocol knowledge base: the official obs-websocket spec is indexed with
repo-rag-mcp (project
obs-websocket-protocol), so agents can look up exact request semantics while driving OBS. - JSON-schema input validation exposed to the client for every tool.
- Faithful mock OBS WebSocket server (
mock-obs) for live testing without OBS, plus an end-to-end integration test that calls every tool through the real MCP protocol.
Installation
Build the release binary with the standard builder:
The binary lands in bin/obs-mcp. Copy it onto your PATH:
Configuration
Set the connection environment variables when launching the server:
OBS_WEBSOCKET_URL— WebSocket URL, defaultws://localhost:4455(wss://TLS is not supported).OBS_WEBSOCKET_PASSWORD— the password configured in OBS under Tools > WebSocket Server Settings. Required when OBS has auth enabled.OBS_START_COMMAND— optional. A shell command (run viash -c) used to launch OBS automatically the first time a connection attempt fails. With this set, the server can start a closed OBS by itself; it waits up to about 25 seconds for OBS to boot and reconnects on its own. Example for a flatpak install:flatpak run com.obsproject.Studio. Requires a display session the launched OBS can use. Note:obs-get-statusonly reads cached state and never triggers the launch; send a real request such asobs-test-connectionto start a closed OBS.
Open Grok registration (~/.opengrok/config.toml):
[]
= "obs-mcp"
= true
Then refresh the MCP list in the TUI (press r). Verify with
open-grok mcp doctor obs-mcp.
For Claude Desktop or any MCP client, point command at the binary and
pass the environment variables:
Architecture
The server is a small, layered program:
src/obs.rs— the OBS WebSocket v5 client. A background task owns the socket, performs the Hello/Identify handshake (with SHA-256 challenge authentication), and routes correlated request/response pairs to awaiting tool calls. When the connection drops it reconnects automatically.src/tools.rs— the tool-building blocks: parameter kinds, JSON-schema construction, and the generic dispatch that turns tool arguments into OBS request data (including parameter renames such asenabledtosceneItemEnabled).src/tools_table.rs— the generated catalog of all 157 tools, produced byscripts/gen_tools_table.py.src/server.rs— the MCP server: a tool router built from the table, plus server metadata and instructions.src/mock.rs— a faithful mock OBS WebSocket server used by the tests and themock-obsexample.
Testing
The live test (tests/live.rs) starts the mock OBS server in-process,
spawns the real obs-mcp binary, performs the MCP handshake over stdio, and
calls all 157 tools with generated sample arguments, asserting every call
succeeds. It also verifies authentication and state coherence (switch a
scene, read it back), and fails on any non-JSON output on stdout (logs must
go to stderr).
Protocol knowledge base
The official obs-websocket protocol specification (cloned from
github.com/obsproject/obs-websocket) is indexed for semantic search
under the repo-rag-mcp project obs-websocket-protocol. Ask
repo-rag-mcp__search with project obs-websocket-protocol for exact
request fields, enums, event payloads, and error codes before calling an
unfamiliar tool. The tool table itself is generated from the reference
projects by scripts/gen_tools_table.py.
Live test
Two options, documented in docs/LIVE_TEST.md:
- Mock OBS:
OBS_MOCK_PASSWORD=secret cargo run --example mock-obs, then pointOBS_WEBSOCKET_URLat the printed URL. No OBS needed; every tool returns a plausible success. - Real OBS: start OBS Studio with the WebSocket server enabled, then run
obs-mcpagainstws://localhost:4455with the correct password.
Project layout
build/ embedded standard builder (copy of the canonical shared builder)
docs/ setup and live-test guides
examples/mock-obs.rs standalone mock OBS WebSocket server
scripts/ tool-table generator
skills/ agent skill for this server
src/ client, tools, server, mock, generated table
tests/live.rs end-to-end MCP test against the mock
Documentation
docs/SETUP.md— OBS and client setup, environment variables, troubleshooting.docs/LIVE_TEST.md— how to test all functions against mock or real OBS.skills/obs-mcp/SKILL.md— agent-facing usage guide.
Known limitations
wss://(TLS) is not supported; usews://or a plainhost:port.- Events (op 5) are received but not surfaced as MCP notifications; the server is request/response only.
- The
Sleeptool is forwarded as-is and blocks the OBS WebSocket pipeline while it runs, exactly as the protocol defines. - Input settings, filter settings and similar free-form objects are passed through unvalidated; the client schema declares them as generic objects.
License
Dual-licensed under MIT or Apache-2.0 (see LICENSE-MIT and LICENSE-APACHE). The tool surface mirrors the public OBS WebSocket v5 protocol of OBS Studio.