obs-studio-mcp

An MCP (Model Context Protocol) server for controlling OBS Studio over obs-websocket v5: scenes, sources, audio, text overlays, streaming, recording, replay buffer, virtual camera, and performance stats.

• Talks to the obs-websocket server built into OBS 28+ (Tools → WebSocket Server Settings).

• Every mutating tool accepts dry_run=true and returns a preview instead of acting — useful guard rails when an agent drives your live stream.

• No secrets in this repo or in your MCP client config.

Quick start

1. In OBS: Tools → WebSocket Server Settings → enable, note the port (default 4455) and password.

2. Provide connection settings via environment:

export OBS_MCP_HOST=127.0.0.1     # default
export OBS_MCP_PORT=4455          # default
export OBS_MCP_PASSWORD=yourpass  # via the default env backend

3. Add to your MCP client:

# Claude Code
claude mcp add obs -s user -- uvx obs-studio-mcp

Related MCP server: OBS MCP Server

Tools

update_text_source is handy for driving on-stream overlays from an agent — question-of-the-day, now-playing, countdowns — anything rendered by a Text source.

Secret storage

The only secret is the websocket password.

Development

pip install -e '.[dev]'
ruff check src tests && pytest

Tests are fully offline (fake obs-websocket client).

License

MIT