obs-studio-mcp
An MCP (Model Context Protocol) server for controlling OBS Studio overobs-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 → WebSocketServer Settings).
- Every mutating tool accepts
dry_run=trueand returns a preview insteadof acting — useful guard rails when an agent drives your live stream. - No secrets in this repo or in your MCP client config.
Quick start
- In OBS: Tools → WebSocket Server Settings → enable, note the port(default 4455) and password.
- 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
- Add to your MCP client:
# Claude Code
claude mcp add obs -s user -- uvx obs-studio-mcp
Tools
| Area | Tools |
|---|---|
| Scenes | list_scenes, switch_scene, set_preview_scene, trigger_transition, set_studio_mode, list_scene_items, set_scene_item_visibility |
| Sources | list_inputs, get_audio_levels, set_mute, set_volume, update_text_source, screenshot_source, media_control |
| Output | stream_status, start_stream, stop_stream, record_status, start_record, stop_record, pause_record, save_replay, set_replay_buffer, set_virtual_cam |
| System | get_stats, list_profiles, switch_profile, list_scene_collections, switch_scene_collection, trigger_hotkey, health_check |
update_text_source is handy for driving on-stream overlays from an agent —question-of-the-day, now-playing, countdowns — anything rendered by a Textsource.
Secret storage
The only secret is the websocket password.
| Backend | Select with | Reads |
|---|---|---|
env (default) |
— | OBS_MCP_PASSWORD |
file |
OBS_MCP_SECRETS=file |
~/.config/obs-studio-mcp/credentials.json (0600) |
vaultproxy |
OBS_MCP_SECRETS=vaultproxy (+ VAULTPROXY_URL) |
a Vaultwarden vault via a local vaultproxy HTTP API |
Development
pip install -e '.[dev]'
ruff check src tests && pytest
Tests are fully offline (fake obs-websocket client).
License
MIT
