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