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

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 Text source.

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

Development Status
- 4 - Beta
Programming Language

Release files for obs-studio-mcp 0.5.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for obs-studio-mcp 0.5.1
File	Size	Uploaded
obs_studio_mcp-0.5.1.tar.gz	14.7 kB	Jul 28, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for obs-studio-mcp 0.5.1
File	Interpreter	ABI	Platform	Reset
obs_studio_mcp-0.5.1-py3-none-any.whl 18.3 kB Jul 28, 2026	Python 3	none	any	Details

Total release size: 33.0 kB

Release files / obs_studio_mcp-0.5.1.tar.gz

Download URL	obs_studio_mcp-0.5.1.tar.gz
Size	14.7 kB
Tags	Source
SHA-256 checksum How to use checksums	`214c729ec6c896fa7f6cc78f0d3940af6010f6b83c45a407442f91df8b5f149a`
BLAKE2b-256 checksum How to use checksums	`028ca367505f4ff2f956616097cbfd6c5bfdcb79d82e4079ace5de3d392520fd`
Upload date	Jul 28, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/aaronckj/obs-studio-mcp
Publishing commit: github.com/aaronckj/obs-studio-mcp/tree/599b382d97ab554bc21951b725bef3faf3085779

Workflow

Publishing configuration: github.com/aaronckj/obs-studio-mcp/blob/599b382d97ab554bc21951b725bef3faf3085779/.github/workflows/publish.yml
Publishing logs: github.com/aaronckj/obs-studio-mcp/actions/runs/30397922526/attempts/1

Artifact

Subject: obs_studio_mcp-0.5.1.tar.gz
SHA-256 checksum: 214c729ec6c896fa7f6cc78f0d3940af6010f6b83c45a407442f91df8b5f149a Verifying attestations

Release files / obs_studio_mcp-0.5.1-py3-none-any.whl

Download URL	obs_studio_mcp-0.5.1-py3-none-any.whl
Size	18.3 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`5cc0c972654e3a3317d150083b2edd8ee5100cdd99673899d834a9f914b5f2a9`
BLAKE2b-256 checksum How to use checksums	`cfcd781258efb9403c269972b97657bf324e1c463d8287e278e9a676bef0d255`
Upload date	Jul 28, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/aaronckj/obs-studio-mcp
Publishing commit: github.com/aaronckj/obs-studio-mcp/tree/599b382d97ab554bc21951b725bef3faf3085779

Workflow

Publishing configuration: github.com/aaronckj/obs-studio-mcp/blob/599b382d97ab554bc21951b725bef3faf3085779/.github/workflows/publish.yml
Publishing logs: github.com/aaronckj/obs-studio-mcp/actions/runs/30397922526/attempts/1

Artifact

Subject: obs_studio_mcp-0.5.1-py3-none-any.whl
SHA-256 checksum: 5cc0c972654e3a3317d150083b2edd8ee5100cdd99673899d834a9f914b5f2a9 Verifying attestations