agentic-obs

A Model Context Protocol (MCP) server that enables AI assistants to control OBS Studio through the OBS WebSocket API.

Overview

This MCP server provides AI agents (like Claude) with programmatic control over OBS Studio, enabling automated scene switching, recording control, streaming management, and more through natural language interactions.

Features

• 69 MCP Tools: Comprehensive control over OBS Studio operations in 8 tool groups
• Scene Management: List, switch, create, and remove OBS scenes
• Scene Presets: Save and restore source visibility configurations
• Recording Control: Start, stop, pause, resume, and monitor recording
• Streaming Control: Start, stop, and monitor streaming
• Source Management: List and control source visibility
• Audio Control: Manage input mute and volume levels
• Screenshot Sources: AI visual monitoring with periodic image capture
• Agentic Scene Design: Create and manipulate sources (text, image, color, browser, media)
• Help & Discovery: Built-in help tool with topic-based guidance
• Status Monitoring: Query OBS connection and operational status
• 4 MCP Resources: Scenes, screenshots, screenshot URLs, and presets exposed as resources
• 13 MCP Prompts: Pre-built workflows for common tasks and diagnostics
• MCP Completions: Autocomplete for prompt arguments and resource URIs
• Claude Skills: Shareable skill packages for advanced AI orchestration
• TUI Dashboard: Terminal interface for status, config, and history (--tui flag)
• Web Dashboard: Browser-based dashboard at http://localhost:8765/

Prerequisites

• Go 1.25.5+ - Download
• OBS Studio 28+ - Includes built-in WebSocket server
• Git - For version control

Installation

Option 1: Install with Go (Recommended)

go install github.com/ironystock/agentic-obs@latest

This installs the agentic-obs binary to your $GOPATH/bin directory.

Option 2: Build from Source

# Clone the repository
git clone https://github.com/ironystock/agentic-obs.git
cd agentic-obs

# Build with Make (recommended - includes version info)
make build

# Or build directly with Go
go build -o agentic-obs .

# Verify the build
./agentic-obs --version

For cross-platform builds, release automation, and advanced build options, see docs/BUILD.md.

Configure OBS Studio

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

Usage

Running the Server

# MCP server mode (default) - if installed via go install
agentic-obs

# TUI dashboard mode - terminal interface for monitoring
agentic-obs --tui
agentic-obs -t

# Or run directly from source
go run main.go
go run main.go --tui

# Or use a built binary
./agentic-obs

TUI Dashboard

The TUI dashboard provides a terminal-based interface with four views:

• Status: OBS connection status, server info, statistics
• Config: Current configuration settings
• History: Action history log with scrolling
• Docs: Embedded documentation with terminal rendering

Navigate with 1/2/3/4 keys or Tab, press q to quit.

On first run, the server will:

1. Auto-detect OBS on localhost:4455
2. Prompt for connection details if auto-detection fails
3. Save successful configuration to SQLite

Connecting to MCP Clients

This server uses stdio transport. Configure your MCP client to execute the agentic-obs command.

Example Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "obs": {
      "command": "agentic-obs"
    }
  }
}

Note: If you built from source or the binary isn't in your PATH, use the full path:

{
  "mcpServers": {
    "obs": {
      "command": "/full/path/to/agentic-obs"
    }
  }
}

Available MCP Tools

S

... View full README on GitHub