OBS ShowRunner MCP Server

AI Director in the Loop - MCP server enabling LLMs to control OBS Studio through high-level "show" and "effect" APIs.

Overview

OBS ShowRunner transforms your LLM (Claude, ChatGPT, etc.) into an AI Director that can:

• 🎬 Control show flow - Start/end shows, switch segments with pre-configured scenes
• 🎨 Trigger effects - Visual effects, overlays, and celebratory animations
• 🎵 Manage audio - Switch between mood-based audio profiles (talk, hype, cinema)
• 📷 See the stream - Take screenshots for visual decision-making
• ✏️ Update content - Dynamically change text, browser sources, and images
• 🔒 Safe by default - Dangerous operations are blocked in strict mode

Quick Start

Prerequisites

• OBS Studio 31+ with WebSocket enabled (default port: 4455)
• Node.js 18+

Installation

# Install globally via npm
npm install -g obs-showrunner-mcp

# Or use npx directly (no installation required)
npx obs-showrunner-mcp

Configure Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "obs-showrunner": {
      "command": "npx",
      "args": ["-y", "obs-showrunner-mcp"],
      "env": {
        "OBS_WEBSOCKET_URL": "ws://localhost:4455",
        "OBS_WEBSOCKET_PASSWORD": "your_password"
      }
    }
  }
}

Or if installed globally:

{
  "mcpServers": {
    "obs-showrunner": {
      "command": "obs-showrunner-mcp",
      "env": {
        "OBS_WEBSOCKET_URL": "ws://localhost:4455",
        "OBS_WEBSOCKET_PASSWORD": "your_password"
      }
    }
  }
}

Usage

Once configured, you can ask Claude things like:

• "Start the show and switch to the gaming segment"
• "Take a screenshot of the current stream"
• "Switch audio to hype mode"
• "Show the title overlay with text 'Welcome!'"
• "Mark this moment as a highlight"

Available Tools

Scene Control

Tool	Description
get_scene_list	Get list of available scenes
set_scene	Switch to a specific scene

Show Control

Tool	Description
start_show	Start a show from a template
end_show	End the current show
switch_segment	Switch to a different segment
extend_segment	Extend current segment timer
get_current_show_state	Get current show state

Audio & Effects

Tool	Description
set_audio_mood	Apply audio mood profile (talk, hype, cinema, etc.)
trigger_effect	Trigger visual effects
show_overlay	Show an overlay
hide_overlay	Hide an overlay
mark_highlight	Mark a highlight timestamp

Vision & Content

Tool	Description
take_stream_snapshot	Capture screenshot (Vision)
update_source_content	Update text/browser/image sources

Admin

Tool	Description
get_obs_health	Check OBS connection status
reconnect_obs	Reconnect to OBS WebSocket
set_safety_mode	Change safety mode
get_debug_config	Get debug configuration

Resources

URI	Description
obs://state/current	Current show state (JSON)

Configuration

Environment variables:

Variable	Default	Description
OBS_WEBSOCKET_URL	ws://localhost:4455	OBS WebSocket URL
OBS_WEBSOCKET_PASSWORD	-	OBS WebSocket password
SAFETY_MODE	strict	Safety mode (strict/normal/debug)
ALLOW_STOP_STREAMING	false	Allow stopping stream
ALLOW_STOP_RECORDING	false	Allow stopping recording
OBS_MIC_INPUT_NAME	Mic/Aux	Microphone source name
OBS_BGM_INPUT_NAME	BGM	BGM source name
OBS_GAME_INPUT_NAME	Game Audio	Game audio source name
OBS_SE_INPUT_NAME	Sound Effects	Sound effects source name

Development

# Clone the repository
git clone https://github.com/takurot/obs-showrunner-mcp.git
cd obs-showrunner-mcp

# Install dependencies
npm install

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Development mode
npm run dev

# Build
npm run build

Safety Modes

• strict (default): Blocks all dangerous operations
• normal: Allows configured operations only
• debug: Dry-run mode, operations are logged but not executed

Architecture

┌─────────────┐     ┌──────────────────────┐     ┌─────────────┐
│   Claude    │────▶│  MCP Server           │────▶│  OBS Studio │
│   Desktop   │◀────│  (obs-showrunner-mcp) │◀────│  WebSocket  │
└─────────────┘     └──────────────────────┘     └─────────────┘
                              │
                    ┌─────────┴─────────┐
                    │                   │
              ┌─────▼─────┐     ┌───────▼───────┐
              │   Show    │     │   Safety      │
              │   State   │     │   Guard       │
              └───────────┘     └───────────────┘

License

MIT