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