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

• 81 MCP Tools: Comprehensive control over OBS Studio operations in 9 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
• Automation Rules: Event-triggered actions and scheduled tasks for hands-free OBS control
• 4 MCP Resources: Scenes, screenshots, screenshot URLs, and presets exposed as resources
• 14 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	Enable/disable tool groups at runtime (session-only or persistent)
list_tool_groups	List all tool groups with descriptions and status

Example: Disable Visual tools for a lighter setup

{
  "tool": "set_tool_config",
  "arguments": {
    "group": "Visual",
    "enabled": false,
    "persist": true
  }
}

Total: 81 tools in 9 groups (Core, Sources, Audio, Layout, Visual, Design, Filters, Transitions, Automation) + Meta (4 always-enabled tools)

MCP Resources

The server exposes OBS data as MCP resources for efficient access and monitoring:

Resource Type	URI Pattern	Content Type	Description
Scenes	obs://scene/{name}	obs-scene (JSON)	Scene configuration with sources and settings
Screenshots	obs://screenshot/{name}	image/png or image/jpeg	Binary screenshot images from capture sources
Screenshot URLs	obs://screenshot-url/{name}	text/plain	HTTP URL for screenshot image access
Presets	obs://preset/{name}	obs-preset (JSON)	Scene preset configurations with source visibility

Usage:

• resources/list - List all available resources
• resources/read - Get detailed resource content
• Resources support notifications for real-time updates
• Completions: Autocomplete available for resource URI names

MCP Prompts

Pre-built workflow prompts guide AI assistants through common OBS tasks:

Prompt	Arguments	Purpose
stream-launch	none	Pre-stream checklist and setup
stream-teardown	none	End-stream cleanup workflow
audio-check	none	Audio verification and diagnostics
visual-check	screenshot_source	Visual layout analysis
health-check	none	Comprehensive OBS diagnostics
problem-detection	screenshot_source	Automated issue detection
preset-switcher	preset_name (optional)	Scene preset management
recording-workflow	none	Recording session guidance
scene-organizer	none	Scene organization and cleanup
quick-status	none	Brief status summary
scene-designer	scene_name, action (optional)	Visual layout creation with Design tools
source-management	scene_name	Manage source visibility and properties
visual-setup	monitor_scene (optional)	Configure screenshot monitoring
automation-setup	rule_type (optional), trigger_event (optional)	Create and manage automation rules (FB-20)

Prompts combine multiple tools into cohesive workflows with best practices built-in. Completions: Autocomplete available for prompt arguments (preset names, screenshot sources, scene names).

Development

Project Structure

agentic-obs/
├── main.go                 # Entry point (MCP server or TUI)
├── config/                 # Configuration management
├── internal/
│   ├── mcp/               # MCP server implementation (81 tools)
│   ├── obs/               # OBS WebSocket client
│   ├── storage/           # SQLite persistence
│   ├── http/              # HTTP server for screenshots and dashboard
│   ├── screenshot/        # Background capture manager
│   └── tui/               # Terminal UI dashboard
├── skills/                 # Claude Skills packages
└── scripts/               # Development helpers

Adding a New Tool

1. Define tool schema in internal/mcp/tools.go
2. Implement handler function
3. Register tool in server initialization
4. Add OBS command wrapper in internal/obs/commands.go if needed

Running Tests

go test ./...

Configuration

Configuration is stored in SQLite (agentic-obs.db) and includes:

• OBS WebSocket connection details (host, port, password)
• Scene and source presets
• User preferences

Troubleshooting

Connection Issues

Problem: "Failed to connect to OBS"

Solutions:

• Ensure OBS Studio is running
• Verify WebSocket server is enabled in OBS (Tools → WebSocket Server Settings)
• Check that port 4455 is not blocked by firewall
• Confirm password matches if authentication is enabled

Permission Issues

Problem: Database write errors

Solutions:

• Ensure the directory is writable
• Check file permissions on agentic-obs.db

Claude Skills

The skills/ directory contains shareable Claude Skills packages that teach AI assistants how to orchestrate agentic-obs tools effectively:

Skill	Purpose
streaming-assistant	Complete streaming workflows (pre-stream, live, teardown)
scene-designer	Visual layout creation with 14 Design tools
audio-engineer	Audio optimization and troubleshooting
preset-manager	Preset lifecycle and organization

Skills use progressive disclosure for token-efficient guidance. See skills/README.md for installation.

Future Enhancements

• Automation rules and macros
• Multi-instance OBS support
• Real-time event notifications
• Additional resource types (filters, transitions)

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

License

[Add your license here]

Resources

• Model Context Protocol
• OBS WebSocket Protocol
• goobs Library

---

Built with:

• Go 1.25.5
• MCP Go SDK v1.1.0
• goobs v1.5.6
• bubbletea/lipgloss (TUI)