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

Scene Management (4 tools)

| Tool | Description | |------|-------------| | list_scenes | List all available scenes and identify current scene | | set_current_scene | Switch to a specific scene | | create_scene | Create a new scene | | remove_scene | Remove a scene |

Recording Control (5 tools)

| Tool | Description | |------|-------------| | start_recording | Start recording | | stop_recording | Stop recording | | pause_recording | Pause current recording | | resume_recording | Resume paused recording | | get_recording_status | Check recording status and details |

Streaming Control (3 tools)

| Tool | Description | |------|-------------| | start_streaming | Start streaming | | stop_streaming | Stop streaming | | get_streaming_status | Check streaming status |

Source Management (3 tools)

| Tool | Description | |------|-------------| | list_sources | List all input sources | | toggle_source_visibility | Show/hide a source in a scene | | get_source_settings | Get source configuration |

Audio Control (4 tools)

| Tool | Description | |------|-------------| | get_input_mute | Check if audio input is muted | | toggle_input_mute | Toggle audio input mute state | | set_input_volume | Set audio input volume (dB or multiplier) | | get_input_volume | Get current volume level (dB and multiplier) |

Scene Presets (6 tools)

| Tool | Description | |------|-------------| | save_scene_preset | Save current scene source states as a named preset | | list_scene_presets | List all saved presets, optionally filter by scene | | get_preset_details | Get detailed information about a specific preset | | apply_scene_preset | Apply a saved preset to restore source visibility | | rename_scene_preset | Rename an existing preset | | delete_scene_preset | Delete a saved preset |

Screenshot Sources (4 tools)

| Tool | Description | |------|-------------| | create_screenshot_source | Create a periodic screenshot capture source for AI visual monitoring | | remove_screenshot_source | Stop and remove a screenshot capture source | | list_screenshot_sources | List all configured sources with status and HTTP URLs | | configure_screenshot_cadence | Update the capture interval for a screenshot source |

Status & Monitoring (1 tool)

| Tool | Description | |------|-------------| | get_obs_status | Get overall OBS status and connection info |

Help & Discovery (1 tool)

| Tool | Description | |------|-------------| | help | Get detailed help on tools, resources, prompts, workflows, or troubleshooting |

Scene Design (14 tools)

Enable AI to create and manipulate OBS sources programmatically.

Source Creation

| Tool | Description | |------|-------------| | create_text_source | Create a text/label source with customizable font and color | | create_image_source | Create an image source from a file path | | create_color_source | Create a solid color source | | create_browser_source | Create a browser source for web content | | create_media_source | Create a media/video source from a file |

Layout Control

| Tool | Description | |------|-------------| | set_source_transform | Set position, scale, and rotation of a source | | get_source_transform | Get current transform properties | | set_source_crop | Set crop values for a source | | set_source_bounds | Set bounds type and size for a source | | set_source_order | Set z-order index (front-to-back ordering) |

Advanced

| Tool | Description | |------|-------------| | set_source_locked | Lock/unlock a source to prevent changes | | duplicate_source | Duplicate a source within or across scenes | | remove_source | Remove a source from a scene | | list_input_kinds | List all available input source types |

Filters (7 tools)

| Tool | Description | |------|-------------| | list_source_filters | List all filters applied to a source | | get_source_filter | Get filter details and settings | | create_source_filter | Add a new filter to a source (color correction, noise suppression, etc.) | | remove_source_filter | Remove a filter from a source | | toggle_source_filter | Enable/disable a filter | | set_source_filter_settings | Modify filter configuration | | list_filter_kinds | List all available filter types |

Transitions (5 tools)

| Tool | Description | |------|-------------| | list_transitions | List all available transitions and current one | | get_current_transition | Get current transition details | | set_current_transition | Change the active transition (Cut, Fade, Swipe, etc.) | | set_transition_duration | Set transition duration in milliseconds | | trigger_transition | Trigger studio mode transition (preview to program) |

Virtual Cam & Replay Buffer (6 tools)

| Tool | Description | |------|-------------| | get_virtual_cam_status | Check if virtual camera output is active | | toggle_virtual_cam | Toggle virtual camera on/off | | get_replay_buffer_status | Check if replay buffer is active | | toggle_replay_buffer | Toggle replay buffer on/off | | save_replay_buffer | Save current replay buffer to file | | get_last_replay | Get the file path of the last saved replay |

Studio Mode & Hotkeys (6 tools)

| Tool | Description | |------|-------------| | get_studio_mode_enabled | Check if studio mode is enabled | | toggle_studio_mode | Enable or disable studio mode | | get_preview_scene | Get the current preview scene (studio mode) | | set_preview_scene | Set the preview scene (studio mode) | | list_hotkeys | List all available OBS hotkeys | | trigger_hotkey_by_name | Trigger a hotkey by name |

Meta Tools (4 tools, always enabled)

| Tool | Description | |------|-------------| | help | Get detailed help on tools, resources, prompts, workflows, or troubleshooting | | get_tool_config | Query current tool group configuration (enabled/disabled state) | | set_tool_config | Enabl