Skip to main content
Glama

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:


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 --version

If 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.git

2. 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.bat

macOS / Linux:

cd OBS_MCP
bash install.sh

The 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.

  1. Open OBS Studio.

  2. Tools → WebSocket Server Settings.

  3. Check Enable WebSocket server.

  4. 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

clean_audio_input — one-call Noise Gate → Suppression → Compressor chain with verified OBS filter parameters. diagnose_av_health — one-call frame-drop/congestion/disk-space diagnosis instead of raw stats

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 OBS_PASSWORD env var doesn't match the password set in OBS's WebSocket Server Settings — or you set a password in OBS but left the env var empty. Don't retype the password from memory: Tools → WebSocket Server Settings → Show Connect Info shows the exact value OBS has stored.

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 get_scene_list / get_input_list first.


Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -x -q

Adding New Tools

  1. Create a module in obs_mcp/tools/ (or add to an existing one).

  2. Export a register(mcp: FastMCP) function.

  3. Define your tools with @mcp.tool() decorators, calling client.execute("RequestType", **params).

  4. Add the module name to _EXPECTED_MODULES in tool_registry.py.

  5. 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 tools
broadcast_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

    B3.1/5.0

    Scored across 148 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count1/5

    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.

    Completeness5/5

    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

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers