OBS MCP — AI Broadcast Control & Automation for OBS Studio

An MCP (Model Context Protocol) server that turns an AI assistant into an AI broadcast operator for OBS Studio. Describe what you want in natural language — the server handles scenes, sources, audio, recording, streaming, transitions, filters, media playback, diagnostics and multi-step workflows over the OBS WebSocket 5.x protocol.

AI Assistant (Claude, opencode, Cursor, ...)
        │  MCP (stdio / sse / streamable-http)
        ▼
    OBS MCP Server
    ┌─────────────────────────────┐
    │ Control / Monitoring        │
    │ Diagnostics / Automation    │
    │ Safety layer (confirmation) │
    └──────────────┬──────────────┘
                   │ OBS WebSocket (default port 4455)
                   ▼
              OBS Studio
           (obs-websocket)

89 tools, 107 tests, no OBS required to run the test suite.

---

Table of contents

1. What you can do
2. Requirements
3. Setup OBS (do this first)
4. Installation
5. Configuration
6. Connecting an AI assistant (MCP client)
7. Running the server
8. Safety model
9. Example session
10. Testing
11. Project structure
12. Troubleshooting

---

What you can do

Connection & status get_obs_status · get_obs_stats · obs_help

Scene management list_scenes · get_current_scene · switch_scene · create_scene · rename_scene · delete_scene · duplicate_scene · get_scene_sources · add_source_to_scene · remove_source_from_scene

Source (input) management list_sources · get_source · get_source_available_kinds · create_source · update_source · delete_source · duplicate_source · show_source · hide_source · set_source_visibility_in_all_scenes

Positioning & layout get_source_transform · set_source_transform (move / scale / rotate / crop) · set_source_index (z-order)

Transitions & studio mode get_transitions · set_scene_transition · set_transition_duration · get_studio_mode_status · set_studio_mode · set_preview_scene · trigger_transition

Audio list_audio_sources · get_audio_status · get_volume · set_volume · mute_source · unmute_source · set_audio_monitor · set_audio_sync_offset · set_audio_track

Filters list_filters · add_filter · remove_filter · get_filter_settings · set_filter_settings · reorder_filters · toggle_filter

Recording & replay buffer get_recording_status · start_recording · stop_recording · pause_recording · resume_recording · get_record_directory · set_record_directory · get_replay_buffer_status · start_replay_buffer · stop_replay_buffer · save_replay_buffer

Streaming get_stream_status · start_stream · stop_stream · get_stream_health · get_stream_service_settings · set_stream_settings · get_output_settings · set_output_settings

Media & VLC playback media_control (play / pause / stop / restart / next / previous) · get_media_time · set_media_time

Hotkeys & configuration get_hotkey_list · trigger_hotkey · get_video_settings · set_video_settings · list_profiles · set_current_profile · create_profile · list_scene_collections · set_current_scene_collection · create_scene_collection

Diagnostics diagnose_obs (full health check) · diagnose_stream · diagnose_recording · diagnose_audio

Automation workflows prepare_recording · prepare_stream · start_recording_session · end_session

---

Requirements

• Python 3.10+
• OBS Studio (any recent version — 28+; tested on 32.x) with the built-in WebSocket server enabled
• One of these AI assistants (any MCP client works):
  • opencode
  • Claude Desktop
  • Cursor
  • Any MCP-capable client

---

Setup OBS (do this first)

1. Install OBS Studio from obsproject.com.
2. Enable the WebSocket server:
   • OBS menu: Tools → WebSocket Server Settings…
   • Check Enable WebSocket server
   • Note the Server Port (default 4455)
   • Check Require authentication and set a password — the server refuses to connect without credentials for security reasons. Save it; you will need it in the next step.
3. Prepare your scenes and sources (optional but recommended):
   • Create scenes (e.g. Intro, Coding, BrB) via Scene dock or + button in the Sources dock.
   • Add sources (webcam, display capture, audio, media) and arrange them.
   • If you plan to use the automation workflows, decide which scene is the "recording scene" and which is the "stream scene".
4. Leave OBS running while you use the AI assistant. The server connects lazily and reconnects automatically if OBS restarts.
5. (Optional) To verify everything works before wiring the AI assistant, run the included demo client — see Testing.

---

Installation

git clone <this-repo> && cd obs-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

This installs the obs-mcp command into the virtual environment (.venv/bin/obs-mcp). All examples below assume the venv is active or use the full path .venv/bin/obs-mcp.

Configuration

Copy the example file and fill in your OBS WebSocket password:

cp .env.example .env
# edit .env, set OBS_PASSWORD to the password you configured in OBS

The server reads the .env file in the project directory, plus any OBS_* environment variables you export (environment variables win).

Variable	Default	Description
OBS_HOST	localhost	OBS WebSocket host
OBS_PORT	4455	OBS WebSocket port (must match Tools → WebSocket Server Settings)
OBS_PASSWORD	(empty)	WebSocket auth password — required when OBS requires authentication
OBS_REQUIRE_CONFIRMATION_HIGH	true	Gate high-risk ops (stream start/stop, deletes) behind confirm=True
OBS_REQUIRE_CONFIRMATION_MEDIUM	false	Gate medium-risk ops (audio, recording) behind confirm=True
OBS_CONNECT_TIMEOUT	5	Seconds to wait for a connection attempt
OBS_RECORDING_SCENE	(empty)	Scene used by prepare_recording / start_recording_session (empty = current scene)
OBS_STREAM_SCENE	(empty)	Scene used by prepare_stream (empty = current scene)
OBS_LOG_LEVEL	INFO	Logging verbosity: DEBUG, INFO, WARNING, ERROR

Security note

OBS_PASSWORD is the same credential that grants full control of your OBS instance (start streams, delete scenes). Never commit it to version control (.env is git-ignored), and use a strong password if your machine is network-exposed.

---

Connecting an AI assistant (MCP client)

opencode

Add a mcp entry to opencode.json (usually ~/.config/opencode/opencode.json):

{
  "mcp": {
    "obs-mcp": {
      "type": "local",
      "command": [
        "/path/to/obs-mcp/.venv/bin/obs-mcp"
      ],
      "enabled": true,
      "environment": {
        "OBS_HOST": "localhost",
        "OBS_PORT": "4455",
        "OBS_PASSWORD": "your-obs-websocket-password"
      }
    }
  }
}

Restart opencode, then ask it things like "check OBS status".

Claude Desktop

Add to claude_desktop_config.json (Claude → Settings → Developer):

{
  "mcpServers": {
    "obs-mcp": {
      "command": "/path/to/obs-mcp/.venv/bin/obs-mcp",
      "args": [],
      "env": {
        "OBS_HOST": "localhost",
        "OBS_PORT": "4455",
        "OBS_PASSWORD": "your-obs-websocket-password"
      }
    }
  }
}

Other clients (Cursor, VS Code, generic)

Point the client at the stdio binary. If your client only supports HTTP servers, run the server with --transport sse or --transport streamable-http and give it the URL of the running server.

---

Running the server

The server is normally launched by your MCP client, but you can also run it standalone to check it starts cleanly:

obs-mcp                          # stdio transport (default, what MCP clients use)
obs-mcp --transport sse          # SSE HTTP transport
obs-mcp --transport streamable-http
python -m server.mcp_server      # equivalent to obs-mcp

A successful stdio start prints nothing but the MCP handshake — clients usually show the server as connected. You can verify OBS connectivity by calling get_obs_status from your assistant, or by running the demo client (needs OBS running):

python examples/demo_client.py

---

Safety model

Operations are classified by risk in server/safety/permissions.py:

Level	Examples	Default policy
Low	status, lists, get_*, switch scene, show/hide source	runs automatically
Medium	volume/mute, create/rename scene, source settings, recording	runs automatically (can be gated via OBS_REQUIRE_CONFIRMATION_MEDIUM=true)
High	start/stop stream, delete scene/source, end_session	requires confirm=true

High-risk tools return confirmation_required unless the caller passes confirm=True — i.e. the AI asks the human first, then proceeds only with explicit confirmation.

---

Example session

User: Check OBS.

AI: OBS is connected. Current scene: Coding. Microphone: Active. Webcam: Active. Recording: OFF. Streaming: OFF.

User: Add a camera in the bottom-right corner of Scene 2 with a full-screen background.

AI: creates a Background color source (1920×1080) and the webcam source, then positions the camera at the bottom-right using set_source_transform.

User: Prepare my coding recording.

AI: calls prepare_recording, reports the setup summary.

User: Everything looks good. Start recording.

AI: calls start_recording_session with confirm=True after asking, confirms, and reports the recording is live.

User: Stop recording and give me a summary.

AI: calls end_session, returns duration and the saved file path.

---

Testing

pip install -e ".[dev]"
pytest

Run the tests from the project root. The suite (107 tests) runs against an in-memory fake OBS — no OBS needed — plus one end-to-end test over the real stdio MCP transport.

---

Project structure

obs-mcp/
├── server/
│   ├── mcp_server.py        # MCP wiring, tool registration, entry point
│   ├── obs_client.py        # OBS WebSocket connection, auth, reconnect, helpers
│   ├── config.py            # OBS_* environment configuration
│   ├── tools/               # one module per feature area
│   │   ├── scenes.py  sources.py  audio.py
│   │   ├── recording.py  streaming.py  transitions helpers
│   │   ├── media.py  filters.py  config.py
│   │   ├── diagnostics.py  automation.py
│   ├── safety/permissions.py  # risk classification + confirmation policy
│   └── models/responses.py    # structured tool responses
├── tests/                   # pytest suite with an in-memory fake OBS
├── examples/demo_client.py  # stdio demo client
├── pyproject.toml
├── features.txt             # full feature checklist
└── .env.example

---

Troubleshooting

Problem	Fix
get_obs_status reports "Could not reach OBS"	OBS not running, or WebSocket server disabled (Tools → WebSocket Server Settings → Enable WebSocket server)
Authentication failed	OBS_PASSWORD does not match the password in OBS WebSocket settings — check both, restart OBS after changing it
Connection refused on a remote machine	Check OBS_HOST/OBS_PORT; make sure the port is reachable and OBS is listening on it
Tools return confirmation_required	The operation is high-risk — pass confirm=true to execute it
set_source_transform does nothing	Keys are snake_case (position_x, scale_y, bounds_width, …); the server converts them for the OBS protocol
Media source won't play	media_control uses OBS_WEBSOCKET_MEDIA_INPUT_ACTION_* actions on media-capable sources (ffmpeg_source / VLC); set_media_time needs the source playing or paused
Assistant can't find the tools after adding the server	Restart the MCP client so it re-reads the config
Tests fail when run from another directory	Always run pytest from the project root