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

Related MCP server: obs-mcp-server

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

Show Control

Audio & Effects

Vision & Content

Admin

Resources

Configuration

Environment variables:

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