obs-mcp 0.2.0

OBS Studio control server for AI assistants via MCP and the OBS WebSocket protocol
Documentation

obs-mcp — OBS Studio control for AI assistants via MCP

github license rust crates.io docs.rs

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:

bash build/linux/build.sh -p .

The binary lands in bin/obs-mcp. Copy it onto your PATH:

cp bin/obs-mcp ~/.local/bin/

Configuration

Set the connection environment variables when launching the server:

  • OBS_WEBSOCKET_URL — WebSocket URL, default ws://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 via sh -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-status only reads cached state and never triggers the launch; send a real request such as obs-test-connection to start a closed OBS.

Open Grok registration (~/.opengrok/config.toml):

[mcp_servers.obs-mcp]
command = "obs-mcp"
enabled = 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:

{
  "mcpServers": {
    "obs-mcp": {
      "command": "obs-mcp",
      "env": {
        "OBS_WEBSOCKET_URL": "ws://localhost:4455",
        "OBS_WEBSOCKET_PASSWORD": "your_password_here"
      }
    }
  }
}

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 as enabled to sceneItemEnabled).
  • src/tools_table.rs — the generated catalog of all 157 tools, produced by scripts/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 the mock-obs example.

Testing

cargo test                # unit tests + live end-to-end test

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:

  1. Mock OBS: OBS_MOCK_PASSWORD=secret cargo run --example mock-obs, then point OBS_WEBSOCKET_URL at the printed URL. No OBS needed; every tool returns a plausible success.
  2. Real OBS: start OBS Studio with the WebSocket server enabled, then run obs-mcp against ws://localhost:4455 with 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; use ws:// or a plain host:port.
  • Events (op 5) are received but not surfaced as MCP notifications; the server is request/response only.
  • The Sleep tool 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.