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

Open OBS Studio
Go to Tools → WebSocket Server Settings
Enable the WebSocket server (default port: 4455)
Set a password (optional but recommended)
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:

Auto-detect OBS on localhost:4455
Prompt for connection details if auto-detection fails
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: 72 tools in 8 groups (Core, Sources, Audio, Layout, Visual, Design, Filters, Transitions) + 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

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 (72 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

Define tool schema in internal/mcp/tools.go
Implement handler function
Register tool in server initialization
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

Built with:

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

Name		Name	Last commit message	Last commit date
Latest commit History 110 Commits
.github/workflows		.github/workflows
config		config
design		design
docs		docs
examples		examples
internal		internal
scripts		scripts
skills		skills
.gitignore		.gitignore
.goreleaser.yml		.goreleaser.yml
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
Makefile		Makefile
PROJECT_PLAN.md		PROJECT_PLAN.md
README.md		README.md
go.mod		go.mod
go.sum		go.sum
main.go		main.go
version.go		version.go
version_test.go		version_test.go

License

ironystock/agentic-obs

Folders and files

Latest commit

History

Repository files navigation

agentic-obs

Overview

Features

Prerequisites

Installation

Option 1: Install with Go (Recommended)

Option 2: Build from Source

Configure OBS Studio

Usage

Running the Server

TUI Dashboard

Connecting to MCP Clients

Available MCP Tools

Scene Management (4 tools)

Recording Control (5 tools)

Streaming Control (3 tools)

Source Management (3 tools)

Audio Control (4 tools)

Scene Presets (6 tools)

Screenshot Sources (4 tools)

Status & Monitoring (1 tool)

Help & Discovery (1 tool)

Scene Design (14 tools)

Source Creation

Layout Control

Advanced

Filters (7 tools)

Transitions (5 tools)

Virtual Cam & Replay Buffer (6 tools)

Studio Mode & Hotkeys (6 tools)

Meta Tools (4 tools, always enabled)

MCP Resources

MCP Prompts

Development

Project Structure

Adding a New Tool

Running Tests

Configuration

Troubleshooting

Connection Issues

Permission Issues

Claude Skills

Future Enhancements

Contributing

License

Resources

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages