obs-mcp-server

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

Requirements

• OBS Studio 28 or later (obs-websocket is built in)
• Node.js 18 or later

OBS Setup

1. Open OBS Studio
2. Go to Tools → WebSocket Server Settings
3. Check Enable WebSocket server
4. Set a password (recommended)
5. Note the port (default: 4455)

Installation

npm install

Create a .env file in the project root:

OBS_WS_URL=ws://localhost:4455
OBS_WS_PASSWORD=your_password_here

Claude Desktop Config

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "obs": {
      "command": "node",
      "args": ["C:\\path\\to\\obs-mcp-server\\obs-mcp-server.js"]
    }
  }
}

Or use npx (no cloning required):

{
  "mcpServers": {
    "obs": {
      "command": "npx",
      "args": ["-y", "obs-mcp-server"],
      "env": {
        "OBS_WS_PASSWORD": "your_password_here"
      }
    }
  }
}

Available Tools

Status & Scenes

Tool	Description
get_status	Current scene, streaming state, recording state + timecodes
list_scenes	List all scenes in the active collection
set_scene	Switch to a named scene

Recording & Streaming

Tool	Description
start_recording	Start recording
stop_recording	Stop recording (returns output file path)
toggle_recording	Toggle recording on/off
start_streaming	Start streaming
stop_streaming	Stop streaming

Sources

Tool	Description
list_sources	List all sources in a scene
set_source_visibility	Show or hide a source

Audio

Tool	Description
list_audio_inputs	List all audio inputs with mute/volume state
set_mute	Mute or unmute an audio input
toggle_mute	Toggle mute on an audio input
set_volume	Set volume (0.0–1.0) on an audio input

Canvas

Tool	Description
set_canvas_resolution	Set base/output resolution and FPS (global per collection)

Scene Management

Tool	Description
create_scene	Create a new empty scene
remove_scene	Delete a scene
rename_scene	Rename a scene

Scene Collections

Tool	Description
list_scene_collections	List all collections, show active
set_scene_collection	Switch to a different collection
create_scene_collection	Create a new scene collection

Profiles

Tool	Description
list_profiles	List all profiles, show active
set_profile	Switch to a different profile
create_profile	Create a new profile
remove_profile	Delete a profile

Misc

Tool	Description
save_screenshot	Save a screenshot of the current output to disk

Notes

• Canvas resolution is a global OBS setting — it applies to all scenes in the current collection. Use separate scene collections for different aspect ratios (e.g. 16:9 vs 9:16 for YouTube Shorts).
• Audio input kinds default to Windows (wasapi_*). On macOS, update the list_audio_inputs handler to use coreaudio_input_capture / coreaudio_output_capture.

License

MIT