agentic-obs

agentic-obs is an MCP server that provides programmatic control over OBS Studio via the OBS WebSocket API. It exposes a rich set of MCP Tools organized into groups for scene management, recording and streaming control, source management, audio, presets, screenshots, and advanced scene design. With this server, an AI assistant can perform tasks such as listing and switching scenes, starting or stopping recording and streaming, adjusting source visibility and transforms, saving and applying scene presets, and capturing periodic screenshots for visual monitoring. The server also offers a TUI dashboard and a Web Dashboard for monitoring status, configuration, and history, enabling easy human inspection during development or debugging. You connect an MCP client to the agentic-obs binary via stdio, and the client can send tool commands and receive structured results and resource URIs for the exposed assets (scenes, screenshots, presets, etc.).

Prerequisites:

• Go 1.25.5+ (or higher)
• OBS Studio 28+ with built-in WebSocket support
• Git

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 MCP server (default)
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 prebuilt binary in PATH
./agentic-obs

Connecting to MCP Clients:

This server uses stdio transport. Configure your MCP client to execute the agentic-obs command. Example Claude Desktop configuration:

{
  "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"
    }
  }
}

Tips and considerations:

• Ensure OBS WebSocket is enabled and accessible (default port 4455; adjust if needed).
• The server exposes 69 MCP tools across 8 groups, including scene management, recording, streaming, sources, audio, presets, screenshots, and scene design. Explore the built-in help tool for guidance on prompts, workflows, and troubleshooting.
• The TUI and Web dashboards provide real-time status, configuration, history, and docs rendering to aid debugging and monitoring.
• When running from source, you can use go run main.go to start the server directly, or compile to a binary for easier distribution.
• If OBS requires authentication, supply the WebSocket password in OBS settings and configure the agent accordingly in your MCP client if authentication hooks are supported.
• For cross-environment deployments, consider using the provided CLI options to run in TUI mode temporarily during setup, then switch to headless operation for production.
• The server also surfaces resources like scenes, screenshots, screenshot URLs, and presets for easy integration into prompts and workflows.