OBS MCP
Controls OBS Studio via obs-websocket v5 protocol, enabling AI assistants to manage scenes, sources, audio, transitions, streaming, recording, virtual camera, replay buffer, media playback, and more.
OBS-MCP connects any MCP-compatible AI assistant to OBS Studio, giving it full control over your stream and recordings. Say "clean up my mic" or "switch to my starting soon scene" and it just happens — no clicking through menus yourself.
148 tools cover the entire obs-websocket v5 protocol — scenes, sources, the full audio mixer, filters, transitions, streaming, recording, virtual camera, replay buffer, studio mode, and output stats. On top of raw control, pipeline tools do the actual job in one call instead of making the AI hand-assemble a filter chain: clean_audio_input builds a verified Noise Gate → Noise Suppression → Compressor chain instead of guessing at OBS's internal filter parameter names, and diagnose_av_health tells you why your frames are dropping instead of handing back raw numbers.
No cloud. Nothing leaves your machine. OBS-MCP is a local WebSocket client that talks directly to OBS Studio's built-in obs-websocket server — your stream, recordings, and scene setup stay on your computer. Bring whatever AI client you already use (Claude Desktop, Claude Code, Cursor, any MCP client) — OBS-MCP handles OBS.
If this is useful to you, a star helps other people find it — that's the whole marketing budget for this project. Want to help keep it maintained? Click the Sponsor badge up top.
Works With
OBS-MCP works with any AI client that supports the Model Context Protocol:
Claude Desktop — Anthropic's desktop app
Claude Code — CLI agent
Cursor — AI code editor with MCP support
Any other MCP-compatible client
Why OBS-MCP?
Pipeline tools, not just raw API access. Most OBS automation stops at "call obs-websocket." OBS-MCP goes further —
clean_audio_input,diagnose_av_health, and other pipelines encode the actual expertise (the right filter chain order, what a dropped-frame stat actually means) so the AI gets it right instead of guessing at parameter names.100% local. No cloud calls, no API keys, nothing leaves your machine — OBS-MCP talks to OBS Studio's own built-in WebSocket server on disk-and-loopback only.
Full protocol coverage. All of obs-websocket v5 is exposed — scenes, audio mixer, filters, transitions, streaming, recording, virtual camera, replay buffer, studio mode — not a curated subset.
Composable with companion tools. Pairs with Reaper-MCP and Audacity-MCP if your stream setup also touches music production or audio cleanup — same AI conversation, different tool for each job.
Related MCP server: Streamfog MCP
New here? What this actually is
If you've never used Claude Desktop or heard of "MCP" before, here's the whole idea in plain terms:
Claude Desktop is Anthropic's free AI chat app (like ChatGPT, but made by Anthropic) — you download it, sign in, and type messages to it like a chatbot.
MCP (Model Context Protocol) is a plug-in system that lets that chat app actually do things on your computer, not just talk. Without MCP, Claude can only give you instructions ("go to Tools menu, click..."). With MCP, Claude can just do it directly.
OBS-MCP is the plug-in for OBS Studio specifically. Once it's installed, you can type things like "clean up my mic" or "switch to my starting soon scene" into Claude, and it actually happens in OBS — no clicking through menus yourself.
You don't need to know any code to use this. The installer below handles everything except two things only you can do: telling OBS to allow the connection, and telling your AI app to use this plug-in. Both are explained step by step.
Quick Start
1. Get OBS-MCP
Option A: Click the green Code button above → Download ZIP → extract it to a folder somewhere easy to find (like your Desktop) — works with nothing pre-installed, easiest on a brand new machine.
Option B: Clone with git (lets you git pull for updates later):
A fresh Windows install doesn't ship with git — check first:
git --versionIf that says "not recognized", install it, then close and reopen your terminal:
winget install --id Git.Git -e --source winget(winget itself ships with Windows 11 and up-to-date Windows 10. If winget isn't found either, grab the installer directly from git-scm.com.)
macOS/Linux almost always have git already — git --version to check, or brew install git / sudo apt install git if not.
git clone https://github.com/xDarkzx/OBS_MCP.git2. Run the installer (installs OBS-MCP and sets up your AI client, automatically)
Windows: either double-click install.bat in File Explorer, or — if you're already in a terminal from the git clone step above — just keep going in the same PowerShell/Command Prompt window (copy-paste both lines):
cd OBS_MCP
.\install.batmacOS / Linux:
cd OBS_MCP
bash install.shThe installer checks you have Python (offers to install it if not), installs the obs-mcp command, and — if you say yes when it asks — automatically writes the config for Claude Desktop and/or LM Studio. No manual JSON editing required. Once it finishes, skip straight to step 3.
Don't even want to clone the repo? OBS-MCP is on PyPI:
pip install obs-mcp(or pip install -e . from inside the folder if you already have the repo cloned/extracted). Either way, this puts an obs-mcp command on your PATH — find where it landed with where obs-mcp (Windows) or which obs-mcp (macOS/Linux) if you ever need the exact file path. Add this to your client's MCP config:
{
"mcpServers": {
"obs": {
"command": "obs-mcp",
"env": {
"OBS_HOST": "localhost",
"OBS_PORT": "4455",
"OBS_PASSWORD": "your_password_here"
}
}
}
}Or for zero footprint (same idea as npx in Node.js — nothing stays installed, uvx runs it fresh each time from its own cache): since there's no permanent obs-mcp binary in this case, point the config at uvx itself instead:
{
"mcpServers": {
"obs": {
"command": "uvx",
"args": ["obs-mcp"],
"env": {
"OBS_HOST": "localhost",
"OBS_PORT": "4455",
"OBS_PASSWORD": "your_password_here"
}
}
}
}If you'd rather not install anything at all, point your client straight at the source file instead of a command — obs_mcp/main.py inside the folder you cloned/extracted is the actual MCP server entry point:
{
"mcpServers": {
"obs": {
"command": "python",
"args": ["-m", "obs_mcp.main"],
"cwd": "/absolute/path/to/the/OBS_MCP/folder/you/extracted",
"env": {
"OBS_HOST": "localhost",
"OBS_PORT": "4455",
"OBS_PASSWORD": "your_password_here"
}
}
}
}Either way: leave OBS_PASSWORD empty ("") if you didn't set one in OBS. If your password has a " or \ in it, escape it for JSON (\" / \\) — everything else can go in as-is. Check your client's own MCP documentation for where its config file lives. Full detail, including exact config-file paths per OS: Installation Guide.
3. Enable the WebSocket server in OBS
This is the one thing the installer genuinely can't do for you — OBS itself has to allow the connection.
OBS Studio ships this built in since v28 — there's nothing to download or install for this part.
Open OBS Studio.
Tools → WebSocket Server Settings.
Check Enable WebSocket server.
Note the Server Port (default
4455, you usually don't need to change this).
No password set yet? Leave it blank — that's fine for a normal single-PC setup.
Already have a password (from a Stream Deck integration, chatbot, or earlier setup)? Don't retype it from memory — click Show Connect Info in that same settings window, which reveals the exact password OBS has stored.
Full walkthrough with screenshots-worth of detail if you get stuck: Installation Guide.
4. Talk to your AI
Restart Claude Desktop if it was already open, then just talk to it normally — for example:
"What OBS scenes do I have?"
"Clean up my mic audio"
"Why are my frames dropping?"
"Switch to my Starting Soon scene"If OBS is running with the WebSocket server enabled, it just works — no special syntax, ask like you'd ask a person.
Features
Category | Tools | What it does |
General | 9 | Version/stats, hotkeys, custom events, vendor requests, persistent data storage |
Config | 15 | Scene collections, profiles, video/canvas settings, stream service destination, record directory |
Sources | 3 | Active-state check and screenshots — works for both inputs and scenes |
Scenes | 12 | List/create/remove/rename scenes, program/preview control, per-scene transition overrides, canvases, groups |
Inputs & Audio | 28 | Create/configure inputs; full mixer — mute, volume, balance, sync offset, monitor type, audio track routing, deinterlace mode |
Transitions | 9 | List/set transitions, duration, settings, T-bar scrubbing, trigger transitions (including studio mode) |
Filters | 10 | Full CRUD on source filter chains — audio and video effects, any order |
Scene Items | 17 | Transform (position/scale/crop), enabled/locked state, z-order, blend mode |
Outputs | 17 | Virtual camera, replay buffer, and any generic named output |
Stream & Record | 14 | Start/stop/toggle, captions, pause/resume, file splitting, chapter markers |
Media | 4 | Playback control for media sources — status, seek, play/pause/stop/restart/next/previous |
UI | 8 | Studio mode, property/filter/interact dialogs, monitor list, projectors |
Pipelines | 2 |
|
148 tools total — full coverage of the obs-websocket v5 protocol (the one intentional omission, Sleep, only functions inside request batches, which this version doesn't implement yet) plus the two composite pipeline tools above.
clean_audio_input — the pipeline tool
Every other tool here is a thin, faithful wrapper over one obs-websocket request. This one isn't — it's the actual thing a streamer wants ("make my mic sound clean") instead of the mechanism ("create three filters with the right internal parameter names in the right order"):
clean_audio_input(input_name="Mic/Aux")Builds a Noise Gate → Noise Suppression (RNNoise) → Compressor chain in the correct signal order, using parameter keys verified against OBS Studio's actual filter source (plugins/obs-filters/*.c) — not guessed from the UI. Skips any stage that's already present instead of duplicating it.
diagnose_av_health — "why is my stream dropping frames?"
diagnose_av_health()Pulls GetStats + GetStreamStatus + GetRecordStatus in one call and interprets them instead of handing back raw numbers: render-thread skip rate points at a GPU/scene bottleneck, output-thread skips with low network congestion point at the encoder, high congestion points at your upload/bitrate, and low disk space gets flagged before it silently kills a recording. Ask your AI "why are my frames dropping" or "is my stream healthy" and it has real numbers to reason from instead of guessing.
Requirements
OBS Studio 28+ (obs-websocket v5 ships built in from v28 onward)
Python 3.10+
An MCP-compatible AI client
Troubleshooting
Problem | Fix |
"Could not connect to OBS" | Make sure OBS Studio is running and Tools → WebSocket Server Settings → Enable WebSocket server is checked. |
"Authentication failed" | Your |
Tool calls hang | Check OBS itself isn't showing a blocking dialog (e.g. a "scene collection changed" prompt) — some requests block until the user dismisses OBS-side UI. |
Scene/input "not found" errors | Names are case-sensitive and must match exactly what's shown in OBS. Call |
Development
# Install dev dependencies
pip install -e ".[dev]"
# Run tests
pytest tests/ -x -qAdding New Tools
Create a module in
obs_mcp/tools/(or add to an existing one).Export a
register(mcp: FastMCP)function.Define your tools with
@mcp.tool()decorators, callingclient.execute("RequestType", **params).Add the module name to
_EXPECTED_MODULESintool_registry.py.That's it — the tool registry auto-discovers it on startup.
See CONTRIBUTING.md for full guidelines.
Support
Found a bug or want a feature? Open an issue.
If OBS-MCP has helped your stream, consider sponsoring:
Your support helps keep this project maintained and free for everyone.
Documentation
Installation Guide — Detailed setup for Windows, macOS, Linux and every supported MCP client
Tools Reference — Every tool grouped by domain, with a one-line description and signature
Architecture — Connection layer, tool registry, pipeline tools, protocol reference
Contributing — How to add tools and contribute
Changelog — Version history and release notes
License
Apache License 2.0 — see LICENSE for details.
Built by Daniel Hodgetts • 𝕏 @daehonz1
Available Tools
148 toolsbroadcast_custom_eventA
Broadcast a CustomEvent to all subscribed obs-websocket clients.
Args: event_data: Arbitrary JSON payload delivered to receivers.
Inputs: event_data (required).
call_vendor_requestC
Call a request registered by a third-party OBS plugin/script vendor.
Args: vendor_name: Unique vendor name registered by the plugin. request_type: The vendor's request type to call. request_data: Optional payload for the vendor request.
Inputs: vendor_name (required), request_type (required), request_data.
clean_audio_inputA
Set up a standard mic-cleanup filter chain in one call: Noise Gate -> Noise Suppression -> Compressor, in that order (order matters — gate first cuts room noise between words, suppression reduces steady background hiss while you're talking, compressor evens out what's left).
Skips any filter kind that already exists on the input by that name instead of duplicating it. Removing a stage later is a normal remove_source_filter call — this only handles the one-shot setup.
Args: input_name: Name of the mic/audio input to clean up. gate/suppression/compressor: Which stages to add (all on by default). gate_open_threshold_db: Gate opens above this level. Should sit slightly below your voice level. Default -26 dB. gate_close_threshold_db: Gate closes below this level. Should sit above the room's noise floor, 5-8 dB below open threshold. Default -32 dB. suppression_method: "rnnoise" (better quality, default) or "speex" (lighter weight, older). compressor_ratio: Compression ratio, 1.0-32.0. Default 3.0 (gentle). compressor_threshold_db: Level compression kicks in at, -60..0 dB. Default -18 dB.
Inputs: input_name (required), gate, compressor, suppression, +5 more.
create_inputA
Create a new input and add it as a scene item to a scene.
Args: input_name: Name for the new input. input_kind: Kind of input to create (see get_input_kind_list). scene_name: Scene to add it to. input_settings: Optional initial settings object. scene_item_enabled: Whether the new scene item starts visible.
Inputs: input_kind (required), input_name (required), scene_name, input_settings, +1 more.
create_profileA
Create a new profile and switch to it.
Inputs: name (required).
create_record_chapterA
Add a chapter marker to the file currently being recorded. Only supported on Hybrid MP4 output as of OBS 30.2.0.
Args: chapter_name: Optional name for the chapter marker.
Inputs: chapter_name.
create_sceneB
Create a new, empty scene.
Args: scene_name: Name for the new scene.
Inputs: scene_name (required).
create_scene_collectionA
Create a new scene collection and switch to it.
Inputs: name (required).
create_scene_itemA
Add an existing source to a scene as a new scene item.
Args: scene_name: Scene to add the item to. source_name: Existing source (input) to place. scene_item_enabled: Whether it starts visible.
Inputs: scene_name (required), source_name (required), scene_item_enabled.
create_source_filterA
Add a new filter to a source.
Args: source_name: Name of the source to add the filter to. filter_name: Name for the new filter. filter_kind: Filter kind (see get_source_filter_kind_list). filter_settings: Optional initial settings.
Inputs: filter_kind (required), filter_name (required), source_name (required), filter_settings.
diagnose_av_healthA
Diagnose why a stream/recording might be dropping frames or stuttering — pulls GetStats + GetStreamStatus + GetRecordStatus in one call and interprets the ratios instead of leaving the AI to fetch three things and do the arithmetic itself.
The three numbers that actually matter, and what each one means:
renderSkippedFrames/renderTotalFrames high: OBS's render thread can't keep up with your scene (too many sources/filters, canvas resolution too high, or GPU-bound). Fix: lower canvas resolution, cut filters, simplify the scene.
outputSkippedFrames/outputTotalFrames high with LOW congestion: encoding can't keep up (CPU/GPU encoder overloaded). Fix: switch to a hardware encoder (NVENC/AMF/QSV), lower the encoder preset, or lower output resolution/fps.
outputCongestion high: the network can't keep up with your bitrate. Fix: lower bitrate, check upload speed.
These thresholds are heuristics, not authoritative OBS cutoffs — a few skipped frames right after starting a stream is normal; this flags sustained skip ratios worth investigating, not noise.
Inputs: no named parameters.
duplicate_scene_itemA
Duplicate a scene item, copying its transform/crop, optionally into a different scene.
Args: scene_name: Scene the item is currently in. scene_item_id: Numeric ID of the item to duplicate. destination_scene_name: Target scene; defaults to the source scene.
Inputs: scene_name (required), scene_item_id (required), destination_scene_name.
get_canvas_listA
List all canvases in OBS (multi-canvas is a newer OBS feature; most setups only have the main canvas).
Inputs: no named parameters.
get_current_preview_sceneA
The scene currently loaded in Preview. Only meaningful in studio mode.
Inputs: no named parameters.
get_current_program_sceneA
The scene currently live on Program (what viewers see).
Inputs: no named parameters.
get_current_scene_transitionA
Full detail on the current transition: kind, duration, whether it's fixed-duration, and its settings.
Inputs: no named parameters.
get_current_scene_transition_cursorA
Current transition progress, 0.0-1.0. Returns 1.0 when no transition is active.
Inputs: no named parameters.
get_group_listA
List all groups (OBS treats groups as a special kind of scene).
Inputs: no named parameters.
get_group_scene_item_listA
Like get_scene_item_list, but for a group (OBS groups are broken under the hood — prefer nested scenes over groups where possible).
Inputs: group_name (required).
get_hotkey_listA
List all hotkey names in OBS. Best-effort — hotkey requests are less reliable than dedicated requests when one exists for the same action.
Inputs: no named parameters.
get_input_audio_balanceA
Get an input's stereo balance (0.0 full left .. 1.0 full right, 0.5 center).
Inputs: input_name (required).
get_input_audio_monitor_typeA
Get an input's monitoring mode (none / monitor-only / monitor-and-output).
Inputs: input_name (required).
get_input_audio_sync_offsetA
Get an input's audio sync offset in milliseconds (can be negative).
Inputs: input_name (required).
get_input_audio_tracksB
Get which of the 6 audio mixer tracks this input is routed to.
Inputs: input_name (required).
get_input_default_settingsA
Default settings object for an input kind — overlay get_input_settings on top of this to reconstruct the full effective settings.
Inputs: input_kind (required).
get_input_deinterlace_field_orderA
Get an input's deinterlace field order. Async inputs only.
Inputs: input_name (required).
get_input_deinterlace_modeA
Get an input's deinterlace mode. Async inputs only (capture cards, etc).
Inputs: input_name (required).
get_input_kind_listA
List every input kind (source type) this OBS install can create.
Inputs: unversioned.
get_input_listA
List all inputs (sources like mic, capture card, browser source, etc).
Args: input_kind: Optional — restrict to one kind (see get_input_kind_list).
Inputs: input_kind.
get_input_muteB
Get an input's mute state.
Inputs: input_name (required).
get_input_properties_list_property_itemsA
Get the items of a dynamic list property on an input — e.g. the available displays for a display-capture source.
Args: input_name: Name of the input. property_name: Name of the list property.
Inputs: input_name (required), property_name (required).
get_input_settingsB
Current (non-default) settings of an input, plus its kind.
Args: input_name: Name of the input.
Inputs: input_name (required).
get_input_volumeA
Get an input's volume as both a linear multiplier and dB.
Inputs: input_name (required).
get_last_replay_buffer_replayB
File path of the last replay buffer save.
Inputs: no named parameters.
get_media_input_statusB
Playback state (playing/paused/stopped/buffering/ended/error), duration, and cursor position of a media source.
Inputs: input_name (required).
get_monitor_listA
List connected monitors (for opening a projector on one).
Inputs: no named parameters.
get_output_listA
List every registered OBS output (stream, record, virtualcam, replay buffer, and any plugin-added outputs).
Inputs: no named parameters.
get_output_settingsC
Get a named output's settings object.
Inputs: output_name (required).
get_output_statusA
Detailed status of a named output: active/reconnecting, timecode, duration, congestion, bytes sent, frame counts.
Inputs: output_name (required).
get_persistent_dataC
Get a value from an OBS persistent-data "slot".
Args: realm: "OBS_WEBSOCKET_DATA_REALM_GLOBAL" or "OBS_WEBSOCKET_DATA_REALM_PROFILE". slot_name: Name of the slot to read.
Inputs: realm (required), slot_name (required).
get_profile_listA
List all profiles and the currently active one.
Inputs: no named parameters.
get_profile_parameterA
Read a raw parameter from the current profile's .ini configuration.
Args: category: Config category, e.g. "Output". name: Parameter name within that category.
Inputs: name (required), category (required).
get_record_directoryA
Current output directory for recordings.
Inputs: no named parameters.
get_record_statusA
Record output status: active, paused, timecode, duration, bytes written.
Inputs: no named parameters.
get_replay_buffer_statusB
Whether the replay buffer is active.
Inputs: no named parameters.
get_scene_collection_listA
List all scene collections and the currently active one.
Inputs: no named parameters.
get_scene_item_blend_modeC
Get a scene item's blend mode.
Inputs: scene_name (required), scene_item_id (required).
get_scene_item_enabledA
Get whether a scene item is currently visible (shown/hidden, not mute).
Inputs: scene_name (required), scene_item_id (required).
get_scene_item_idA
Find a scene item's numeric ID by the source name it references.
Args: scene_name: Scene or group to search. source_name: Name of the source to find. search_offset: Matches to skip. -1 = last (topmost) match.
Inputs: scene_name (required), source_name (required), search_offset.
get_scene_item_indexA
Get a scene item's stacking position (0 = bottom of the source list).
Inputs: scene_name (required), scene_item_id (required).
get_scene_item_listA
List every scene item (placed source) in a scene.
Inputs: scene_name (required).
get_scene_item_lockedA
Get a scene item's lock state (locked items can't be moved/resized in the UI).
Inputs: scene_name (required), scene_item_id (required).
get_scene_item_sourceB
Get the source name/UUID a scene item references.
Inputs: scene_name (required), scene_item_id (required).
get_scene_item_transformC
Get a scene item's position, scale, rotation, and crop.
Inputs: scene_name (required), scene_item_id (required).
get_scene_listA
List every scene, plus the current program and preview scene names.
Inputs: no named parameters.
get_scene_transition_listA
List every configured transition and which one is current.
Inputs: no named parameters.
get_scene_transition_overrideA
Get the transition overridden for a specific scene, if any.
Args: scene_name: Name of the scene.
Inputs: scene_name (required).
get_source_activeA
Check whether a source (input or scene) is currently showing in Program (videoActive) and/or visible anywhere in the UI (videoShowing).
Args: source_name: Name of the input or scene.
Inputs: source_name (required).
get_source_filterB
Get a filter's enabled state, chain index, kind, and settings.
Inputs: filter_name (required), source_name (required).
get_source_filter_default_settingsD
Default settings object for a filter kind.
Inputs: filter_kind (required).
get_source_filter_kind_listA
List every filter kind this OBS install supports (noise_suppress_filter, noise_gate_filter, compressor_filter, color_filter, chroma_key_filter, etc).
Inputs: no named parameters.
get_source_filter_listA
List all filters on a source (input or scene), in chain order.
Args: source_name: Name of the source.
Inputs: source_name (required).
get_source_screenshotA
Get a Base64-encoded screenshot of a source (input or scene) — use this to actually SEE what's on stream. Check get_version's supportedImageFormats for valid image_format values on this OBS build.
Args: source_name: Name of the input or scene to capture. image_format: e.g. "png", "jpg". image_width/image_height: Optional scale-to-fit dimensions (8-4096). Omit to use the source's native resolution. image_compression_quality: 0 (max compression) to 100 (uncompressed), -1 for format default.
Inputs: source_name (required), image_width, image_format, image_height, +1 more.
get_special_inputsA
Names of the built-in special audio inputs: Desktop Audio 1/2, Mic/Aux 1-4. Use these names to control the default audio channels.
Inputs: no named parameters.
get_statsA
Live perf stats: CPU/memory usage, active FPS, render/output skipped frames, disk space. Use to check for dropped-frame problems mid-stream.
Inputs: no named parameters.
get_stream_service_settingsB
Current stream destination service type and settings (server/key etc).
Inputs: no named parameters.
get_stream_statusA
Stream output status: active/reconnecting, timecode, duration, congestion, bytes sent, skipped/total frames.
Inputs: no named parameters.
get_studio_mode_enabledA
Whether studio mode (separate Preview/Program) is enabled.
Inputs: no named parameters.
get_transition_kind_listA
List every transition kind this OBS install supports (Cut, Fade, Stinger, etc).
Inputs: no named parameters.
get_versionA
OBS/obs-websocket version info, platform, and the full list of requests available on this connection (availableRequests).
Inputs: no named parameters.
get_video_settingsA
Current canvas/output resolution and FPS (as a fraction — divide fpsNumerator by fpsDenominator for the true FPS).
Inputs: no named parameters.
get_virtual_cam_statusB
Whether the virtual camera output is active.
Inputs: no named parameters.
offset_media_input_cursorA
Seek a media source relative to its current position. No bounds checking.
Args: input_name: Name of the media input. offset_ms: Milliseconds to offset by (negative = seek backward).
Inputs: offset_ms (required), input_name (required).
open_input_filters_dialogC
Open an input's Filters dialog in the OBS UI.
Inputs: input_name (required).
open_input_interact_dialogA
Open an input's Interact dialog in the OBS UI.
Inputs: input_name (required).
open_input_properties_dialogB
Open an input's Properties dialog in the OBS UI.
Inputs: input_name (required).
open_source_projectorA
Open a fullscreen or windowed projector for a specific source.
Args: source_name: Name of the source (input or scene). monitor_index: Monitor to open fullscreen on, -1 for windowed. projector_geometry: Qt-base64 window geometry for windowed mode.
Inputs: source_name (required), monitor_index, projector_geometry.
open_video_mix_projectorA
Open a fullscreen or windowed projector for Preview/Program/Multiview.
Args: video_mix_type: OBS_WEBSOCKET_VIDEO_MIX_TYPE_PREVIEW, _PROGRAM, or _MULTIVIEW. monitor_index: Monitor to open fullscreen on (see get_monitor_list), -1 for windowed. projector_geometry: Qt-base64 window geometry for windowed mode; mutually exclusive with monitor_index.
Inputs: video_mix_type (required), monitor_index, projector_geometry.
pause_recordA
Pause the active recording.
Inputs: no named parameters.
press_input_properties_buttonA
Press a button in an input's properties — e.g. "refreshnocache" to reload a browser source.
Args: input_name: Name of the input. property_name: Name of the button property to press.
Inputs: input_name (required), property_name (required).
remove_inputA
Delete an input. Removes all its scene items too.
Args: input_name: Name of the input to remove.
Inputs: input_name (required).
remove_profileA
Remove a profile. If it's the active one, OBS switches away first.
Inputs: name (required).
remove_sceneB
Delete a scene.
Args: scene_name: Name of the scene to remove.
Inputs: scene_name (required).
remove_scene_itemA
Remove a scene item from a scene (does not delete the underlying source).
Inputs: scene_name (required), scene_item_id (required).
remove_source_filterB
Remove a filter from a source.
Inputs: filter_name (required), source_name (required).
resume_recordA
Resume a paused recording.
Inputs: no named parameters.
save_replay_bufferA
Save the last N seconds from the replay buffer to disk — the "instant replay" clip-save action.
Inputs: no named parameters.
save_source_screenshotA
Save a screenshot of a source (input or scene) directly to disk.
Args: source_name: Name of the input or scene to capture. image_file_path: Absolute path to save to, e.g. C:/renders/shot.png. image_format: e.g. "png", "jpg". image_width/image_height: Optional scale-to-fit dimensions (8-4096). image_compression_quality: 0 (max compression) to 100 (uncompressed), -1 for format default.
Inputs: source_name (required), image_file_path (required), image_width, image_format, +2 more.
send_stream_captionC
Send CEA-608 caption text over the live stream output.
Args: caption_text: Caption text to send.
Inputs: caption_text (required).
set_current_preview_sceneA
Load a scene into Preview (studio mode only) — stage it before transitioning to Program with trigger_studio_mode_transition.
Args: scene_name: Exact scene name.
Inputs: scene_name (required).
set_current_profileB
Switch to a profile by name.
Inputs: name (required).
set_current_program_sceneA
Switch the live Program scene — the core "cut to this scene" action.
Args: scene_name: Exact scene name (see get_scene_list).
Inputs: scene_name (required).
set_current_scene_collectionA
Switch to a scene collection by name. Blocks until the switch completes.
Inputs: name (required).
set_current_scene_transitionB
Make a transition the active one for the next scene switch.
Args: transition_name: Name of the transition to activate.
Inputs: transition_name (required).
set_current_scene_transition_durationA
Set the duration of the current transition, if it isn't fixed-duration.
Args: duration_ms: Duration in milliseconds, 50-20000.
Inputs: duration_ms (required).
set_current_scene_transition_settingsB
Configure the current transition (e.g. a Stinger's video file path).
Args: settings: Settings object for the transition. overlay: True = merge on top of current settings, False = replace.
Inputs: settings (required), overlay.
set_input_audio_balanceA
Set an input's stereo balance.
Args: input_name: Name of the input. balance: 0.0 (full left) to 1.0 (full right), 0.5 = center.
Inputs: balance (required), input_name (required).
set_input_audio_monitor_typeA
Set an input's monitoring mode.
Args: input_name: Name of the input. monitor_type: One of OBS_MONITORING_TYPE_NONE, OBS_MONITORING_TYPE_MONITOR_ONLY, OBS_MONITORING_TYPE_MONITOR_AND_OUTPUT.
Inputs: input_name (required), monitor_type (required).
set_input_audio_sync_offsetA
Set an input's audio sync offset — use to fix audio/video drift.
Args: input_name: Name of the input. offset_ms: Offset in milliseconds, range -950..20000.
Inputs: offset_ms (required), input_name (required).
set_input_audio_tracksA
Set which audio mixer tracks an input is routed to.
Args: input_name: Name of the input. audio_tracks: Object like {"1": true, "2": false, ...} for tracks 1-6.
Inputs: input_name (required), audio_tracks (required).
set_input_deinterlace_field_orderA
Set an input's deinterlace field order.
Args: input_name: Name of the input. field_order: OBS_DEINTERLACE_FIELD_ORDER_TOP or _BOTTOM.
Inputs: input_name (required), field_order (required).
set_input_deinterlace_modeA
Set an input's deinterlace mode.
Args: input_name: Name of the input. mode: One of OBS_DEINTERLACE_MODE_DISABLE, _DISCARD, _RETRO, _BLEND, _BLEND_2X, _LINEAR, _LINEAR_2X, _YADIF, _YADIF_2X.
Inputs: mode (required), input_name (required).
set_input_muteC
Mute or unmute an input.
Inputs: input_name (required), input_muted (required).
set_input_nameB
Rename an input.
Args: input_name: Current name. new_input_name: New name.
Inputs: input_name (required), new_input_name (required).
set_input_settingsA
Set an input's settings.
Args: input_name: Name of the input. input_settings: Settings object to apply. overlay: True = merge on top of current settings, False = reset to defaults first then apply.
Inputs: input_name (required), input_settings (required), overlay.
set_input_volumeA
Set an input's volume — pass exactly one of volume_db or volume_mul.
Args: input_name: Name of the input. volume_db: Volume in dB, range -100..26. volume_mul: Volume as a linear multiplier, range 0..20.
Inputs: input_name (required), volume_db, volume_mul.
set_media_input_cursorA
Seek a media source to an absolute position. No bounds checking.
Args: input_name: Name of the media input. cursor_ms: Position in milliseconds.
Inputs: cursor_ms (required), input_name (required).
set_output_settingsB
Set a named output's settings object.
Inputs: settings (required), output_name (required).
set_persistent_dataA
Set a value in an OBS persistent-data "slot" — useful for storing state the AI needs to remember across tool calls (e.g. giveaway winners).
Args: realm: "OBS_WEBSOCKET_DATA_REALM_GLOBAL" or "OBS_WEBSOCKET_DATA_REALM_PROFILE". slot_name: Name of the slot to write. slot_value: Any JSON-serializable value.
Inputs: realm (required), slot_name (required), slot_value (required).
set_profile_parameterA
Write a raw parameter into the current profile's .ini configuration. Advanced/low-level — prefer a dedicated request when one exists.
Args: category: Config category, e.g. "Output". name: Parameter name within that category. value: New value, or None to delete the parameter.
Inputs: name (required), value (required), category (required).
set_record_directoryA
Set the output directory recordings are written to.
Args: path: Absolute directory path.
Inputs: path (required).
set_scene_item_blend_modeA
Set a scene item's blend mode.
Args: scene_name: Scene the item is in. scene_item_id: Numeric ID of the item. blend_mode: One of OBS_BLEND_NORMAL, _ADDITIVE, _SUBTRACT, _SCREEN, _MULTIPLY, _LIGHTEN, _DARKEN.
Inputs: blend_mode (required), scene_name (required), scene_item_id (required).
set_scene_item_enabledA
Show or hide a scene item.
Args: scene_name: Scene the item is in. scene_item_id: Numeric ID of the item. enabled: True = visible, False = hidden.
Inputs: enabled (required), scene_name (required), scene_item_id (required).
set_scene_item_indexA
Reorder a scene item's stacking position (z-order).
Args: scene_name: Scene the item is in. scene_item_id: Numeric ID of the item. index: New position, >= 0 (0 = bottom of the source list).
Inputs: index (required), scene_name (required), scene_item_id (required).
set_scene_item_lockedB
Lock or unlock a scene item.
Inputs: locked (required), scene_name (required), scene_item_id (required).
set_scene_item_transformA
Set a scene item's position/scale/rotation/crop.
Args: scene_name: Scene the item is in. scene_item_id: Numeric ID of the item. transform: Object with any of positionX/positionY, rotation, scaleX/scaleY, alignment, boundsType/boundsAlignment/ boundsWidth/boundsHeight, cropLeft/Right/Top/Bottom.
Inputs: transform (required), scene_name (required), scene_item_id (required).
set_scene_nameB
Rename a scene.
Args: scene_name: Current name of the scene. new_scene_name: New name.
Inputs: scene_name (required), new_scene_name (required).
set_scene_transition_overrideA
Override which transition (and/or duration) is used when switching INTO this specific scene, instead of the global current transition.
Args: scene_name: Name of the scene. transition_name: Transition to use, or None to clear the override. transition_duration_ms: Duration override in ms (50-20000), or None to clear.
Inputs: scene_name (required), transition_name, transition_duration_ms.
set_source_filter_enabledB
Enable or disable a filter without removing it.
Inputs: filter_name (required), source_name (required), filter_enabled (required).
set_source_filter_indexA
Reorder a filter within a source's filter chain.
Args: source_name: Name of the source. filter_name: Name of the filter to move. filter_index: New position, >= 0 (0 = first in chain).
Inputs: filter_name (required), source_name (required), filter_index (required).
set_source_filter_nameC
Rename a filter.
Inputs: filter_name (required), source_name (required), new_filter_name (required).
set_source_filter_settingsA
Configure a filter's parameters.
Args: source_name: Name of the source. filter_name: Name of the filter. filter_settings: Settings object. overlay: True = merge on top of current settings, False = reset to defaults first.
Inputs: filter_name (required), source_name (required), filter_settings (required), overlay.
set_stream_service_settingsA
Set the stream destination. For a plain custom RTMP target, use service_type="rtmp_custom" and settings={"server": "...", "key": "..."}.
Args: service_type: e.g. "rtmp_custom" or "rtmp_common". settings: Service-specific settings object.
Inputs: settings (required), service_type (required).
set_studio_mode_enabledA
Enable or disable studio mode.
Inputs: enabled (required).
set_tbar_positionA
Set the T-bar position for manual transition scrubbing.
Args: position: 0.0-1.0. release: Set False only if you're about to send another position update immediately after this one.
Inputs: position (required), release.
set_video_settingsA
Change canvas/output resolution and/or FPS. Width/height fields must be set in pairs (can't change baseWidth without baseHeight, etc). Range 1-4096 for all resolution fields.
Inputs: base_width, base_height, output_width, fps_numerator, +2 more.
split_record_fileA
Split the current recording into a new file right now — useful for keeping individual segments a manageable size on long streams.
Inputs: no named parameters.
start_outputC
Start a named output.
Inputs: output_name (required).
start_recordA
Start recording to disk (see config_tools.get/set_record_directory for where files land).
Inputs: no named parameters.
start_replay_bufferB
Start the replay buffer.
Inputs: no named parameters.
start_streamB
Go live. Requires stream service settings to already be configured (see config_tools.set_stream_service_settings).
Inputs: no named parameters.
start_virtual_camB
Start the virtual camera.
Inputs: no named parameters.
stop_outputB
Stop a named output.
Inputs: output_name (required).
stop_recordA
Stop recording. Returns the saved file's path.
Inputs: no named parameters.
stop_replay_bufferA
Stop the replay buffer.
Inputs: no named parameters.
stop_streamB
End the stream.
Inputs: no named parameters.
stop_virtual_camA
Stop the virtual camera.
Inputs: no named parameters.
toggle_input_muteC
Toggle an input's mute state.
Inputs: input_name (required).
toggle_outputB
Toggle a named output on/off.
Inputs: output_name (required).
toggle_recordA
Toggle recording on/off.
Inputs: no named parameters.
toggle_record_pauseA
Toggle pause on the active recording.
Inputs: no named parameters.
toggle_replay_bufferA
Toggle the replay buffer on/off.
Inputs: no named parameters.
toggle_streamB
Toggle the stream on/off.
Inputs: no named parameters.
toggle_virtual_camB
Toggle the virtual camera on/off.
Inputs: no named parameters.
trigger_hotkey_by_key_sequenceC
Trigger a hotkey by simulating a key press + modifiers.
Args: key_id: OBS key ID (see obs-studio's obs-hotkeys.h for the list). shift/control/alt/command: Modifier keys to hold.
Inputs: alt, shift, key_id, command, +1 more.
trigger_hotkey_by_nameA
Trigger a hotkey by its name (see get_hotkey_list).
Args: hotkey_name: Name of the hotkey to trigger. context_name: Optional hotkey context name.
Inputs: hotkey_name (required), context_name.
trigger_media_input_actionA
Trigger a transport action on a media source.
Args: input_name: Name of the media input. action: One of OBS_WEBSOCKET_MEDIA_INPUT_ACTION_PLAY, _PAUSE, _STOP, _RESTART, _NEXT, _PREVIOUS.
Inputs: action (required), input_name (required).
trigger_studio_mode_transitionA
Trigger the current transition — same as clicking the Transition button in studio mode. Cuts Preview to Program.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 148 tools
Most tools map cleanly to distinct OBS resources and actions, but with 148 tools there are a few easily confused groups: get_scene_list vs get_scene_collection_list, get_output_status vs get_stream_status, and trigger_hotkey_by_name vs trigger_hotkey_by_key_sequence. Descriptions are detailed and usually clarify the differences, so an agent can disambiguate with careful reading, but misselection risk is non-trivial.
Every tool follows a consistent verb_noun pattern in snake_case (get_input_mute, set_current_program_scene, toggle_record_pause). Even composite tools like clean_audio_input and diagnose_av_health fit the pattern. No camelCase, no inconsistent verb styles, and no random names.
148 tools is far beyond any reasonable MCP server scope and exceeds the 50+ threshold for an extreme mismatch. Even though OBS is a complex application, this quantity will overwhelm an agent's ability to select among options, making the tool set unwieldy regardless of how legitimate each individual tool may be.
The tool set covers the full OBS WebSocket API surface: scenes, inputs, scene items, filters, transitions, outputs, profiles, scene collections, settings, hotkeys, media, screenshots, projectors, and custom events. There are a few minor gaps (e.g., no remove_scene_collection, no transition creation), but they are easily worked around. Core workflows like 'set up a stream, capture sources, switch scenes, record, and go live' are fully supported.
Maintenance
Related MCP Connectors
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to control Unreal E…
Direct AI video, image, music and storyboard production from any MCP client.
Use AI models for chat, image, and video generation from Claude Code and other MCP hosts.
Related MCP Servers
- AlicenseAqualityDmaintenanceAn MCP (Model Context Protocol) server for controlling OBS Studio via the built-in obs-websocket plugin. Lets Claude control your scenes, recording, streaming, audio, and more.2613 npm1MIT
- AlicenseAqualityBmaintenanceAI-driven AR lens orchestrator for live OBS streams that enables control of Streamfog face filters, AR effects, and Vtuber avatars through MCP tools via the local Streamer.bot WebSocket bridge.52MIT
- AlicenseNot gradedqualityCmaintenanceModel Context Protocol server for OBS Studio43 npmMIT
- AlicenseBqualityDmaintenanceMCP server enabling LLMs to control OBS Studio through high-level show and effect APIs.18MIT