{"id":"659fcf1a-c72e-41e0-89a9-a204a8d0281d","slug":"agentic-obs","kind":"mcp","name":"agentic-obs","summary":"agentic-obs: A Model Context Protocol (MCP) server that provides AI assistants with programmatic control over OBS Studio via the OBS WebSocket API. This server enables AI agents to manage scenes, sour","owner":"ironystock","repoUrl":"https://github.com/ironystock/agentic-obs","license":"MIT","licenseTier":"permissive","trust":"community","stars":38,"match":null,"fewStars":false,"format":"mcp","createdAt":"2025-12-15T02:10:02.000Z","addedAt":"2026-10-14T03:47:04.644Z","logoUrl":"https://avatars.githubusercontent.com/u/43087795?u=223c60dafb829535cce2512adde6f2db3f717c01&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["cloud-infra","memory-knowledge"],"tags":["agentic","agents","obs"],"runtime":"go","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-15T03:19:51.994Z","sample":false,"url":"https://conduits.dev/tools/agentic-obs","language":"Go","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# agentic-obs\n\nA Model Context Protocol (MCP) server that enables AI assistants to control OBS Studio through the OBS WebSocket API.\n\n## Overview\n\nThis 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.\n\n## Features\n\n- **81 MCP Tools**: Comprehensive control over OBS Studio operations in 9 tool groups\n- **Scene Management**: List, switch, create, and remove OBS scenes\n- **Scene Presets**: Save and restore source visibility configurations\n- **Recording Control**: Start, stop, pause, resume, and monitor recording\n- **Streaming Control**: Start, stop, and monitor streaming\n- **Source Management**: List and control source visibility\n- **Audio Control**: Manage input mute and volume levels\n- **Screenshot Sources**: AI visual monitoring with periodic image capture\n- **Agentic Scene Design**: Create and manipulate sources (text, image, color, browser, media)\n- **Help & Discovery**: Built-in help tool with topic-based guidance\n- **Status Monitoring**: Query OBS connection and operational status\n- **Automation Rules**: Event-triggered actions and scheduled tasks for hands-free OBS control\n- **4 MCP Resources**: Scenes, screenshots, screenshot URLs, and presets exposed as resources\n- **14 MCP Prompts**: Pre-built workflows for common tasks and diagnostics\n- **MCP Completions**: Autocomplete for prompt arguments and resource URIs\n- **Claude Skills**: Shareable skill packages for advanced AI orchestration\n- **TUI Dashboard**: Terminal interface for status, config, and history (`--tui` flag)\n- **Web Dashboard**: Browser-based dashboard at `http://localhost:8765/`\n\n## Prerequisites\n\n- **Go 1.25.5+** - [Download](https://go.dev/dl/)\n- **OBS Studio 28+** - Includes built-in WebSocket server\n- **Git** - For version control\n\n## Installation\n\n### Option 1: Install with Go (Recommended)\n\n```bash\ngo install github.com/ironystock/agentic-obs@latest\n```\n\nThis installs the `agentic-obs` binary to your `$GOPATH/bin` directory.\n\n### Option 2: Build from Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/ironystock/agentic-obs.git\ncd agentic-obs\n\n# Build with Make (recommended - includes version info)\nmake build\n\n# Or build directly with Go\ngo build -o agentic-obs .\n\n# Verify the build\n./agentic-obs --version\n```\n\nFor cross-platform builds, release automation, and advanced build options, see [docs/BUILD.md](docs/BUILD.md).\n\n### Configure OBS Studio\n\n1. Open OBS Studio\n2. Go to **Tools → WebSocket Server Settings**\n3. Enable the WebSocket server (default port: 4455)\n4. Set a password (optional but recommended)\n5. Note your connection details\n\n## Usage\n\n### Running the Server\n\n```bash\n# MCP server mode (default) - if installed via go install\nagentic-obs\n\n# TUI dashboard mode - terminal interface for monitoring\nagentic-obs --tui\nagentic-obs -t\n\n# Or run directly from source\ngo run main.go\ngo run main.go --tui\n\n# Or use a built binary\n./agentic-obs\n```\n\n### TUI Dashboard\n\nThe TUI dashboard provides a terminal-based interface with four views:\n- **Status**: OBS connection status, server info, statistics\n- **Config**: Current configuration settings\n- **History**: Action history log with scrolling\n- **Docs**: Embedded documentation with terminal rendering\n\nNavigate with `1/2/3/4` keys or Tab, press `q` to quit.\n\nOn first run, the server will:\n1. Auto-detect OBS on `localhost:4455`\n2. Prompt for connection details if auto-detection fails\n3. Save successful configuration to SQLite\n\n### Connecting to MCP Clients\n\nThis server uses stdio transport. Configure your MCP client to execute the `agentic-obs` command.\n\nExample Claude Desktop configuration (`claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"obs\": {\n      \"command\": \"agentic-obs\"\n    }\n  }\n}\n```\n\n**Note:** If you built from source or the binary isn't in your PATH, use the full path:\n```json\n{\n  \"mcpServers\": {\n    \"obs\": {\n      \"command\": \"/full/path/to/agentic-obs\"\n    }\n  }\n}\n```\n\n## Available MCP Tools\n\n### Scene Management (4 tools)\n\n| Tool | Description |\n|------|-------------|\n| `list_scenes` | List all available scenes and identify current scene |\n| `set_current_scene` | Switch to a specific scene |\n| `create_scene` | Create a new scene |\n| `remove_scene` | Remove a scene |\n\n### Recording Control (5 tools)\n\n| Tool | Description |\n|------|-------------|\n| `start_recording` | Start recording |\n| `stop_recording` | Stop recording |\n| `pause_recording` | Pause current recording |\n| `resume_recording` | Resume paused recording |\n| `get_recording_status` | Check recording status and details |\n\n### Streaming Control (3 tools)\n\n| Tool | Description |\n|------|-------------|\n| `start_streaming` | Start streaming |\n| `stop_streaming` | Stop streaming |\n| `get_streaming_status` | Check streaming status |\n\n### Source Management (3 tools)\n\n| Tool | Description |\n|------|-------------|\n| `list_sources` | List all input sources |\n| `toggle_source_visibility` | Show/hide a source in a scene |\n| `get_source_settings` | Get source configuration |\n\n### Audio Control (4 tools)\n\n| Tool | Description |\n|------|-------------|\n| `get_input_mute` | Check if audio input is muted |\n| `toggle_input_mute` | Toggle audio input mute state |\n| `set_input_volume` | Set audio input volume (dB or multiplier) |\n| `get_input_volume` | Get current volume level (dB and multiplier) |\n\n### Scene Presets (6 tools)\n\n| Tool | Description |\n|------|-------------|\n| `save_scene_preset` | Save current scene source states as a named preset |\n| `list_scene_presets` | List all saved presets, optionally filter by scene |\n| `get_preset_details` | Get detailed information about a specific preset |\n| `apply_scene_preset` | Apply a saved preset to restore source visibility |\n| `rename_scene_preset` | Rename an existing preset |\n| `delete_scene_preset` | Delete a saved preset |\n\n### Screenshot Sources (4 tools)\n\n| Tool | Description |\n|------|-------------|\n| `create_screenshot_source` | Create a periodic screenshot capture source for AI visual monitoring |\n| `remove_screenshot_source` | Stop and remove a screenshot capture source |\n| `list_screenshot_sources` | List all configured sources with status and HTTP URLs |\n| `configure_screenshot_cadence` | Update the capture interval for a screenshot source |\n\n### Status & Monitoring (1 tool)\n\n| Tool | Description |\n|------|-------------|\n| `get_obs_status` | Get overall OBS status and connection info |\n\n### Help & Discovery (1 tool)\n\n| Tool | Description |\n|------|-------------|\n| `help` | Get detailed help on tools, resources, prompts, workflows, or troubleshooting |\n\n### Scene Design (14 tools)\n\nEnable AI to create and manipulate OBS sources programmatically.\n\n#### Source Creation\n\n| Tool | Description |\n|------|-------------|\n| `create_text_source` | Create a text/label source with customizable font and color |\n| `create_image_source` | Create an image source from a file path |\n| `create_color_source` | Create a solid color source |\n| `create_browser_source` | Create a browser source for web content |\n| `create_media_source` | Create a media/video source from a file |\n\n#### Layout Control\n\n| Tool | Description |\n|------|-------------|\n| `set_source_transform` | Set position, scale, and rotation of a source |\n| `get_source_transform` | Get current transform properties |\n| `set_source_crop` | Set crop values for a source |\n| `set_source_bounds` | Set bounds type and size for a source |\n| `set_source_order` | Set z-order index (front-to-back ordering) |\n\n#### Advanced\n\n| Tool | Description |\n|------|-------------|\n| `set_source_locked` | Lock/unlock a source to prevent changes |\n| `duplicate_source` | Duplicate a source within or across scenes |\n| `remove_source` | Remove a source from a scene |\n| `list_input_kinds` | List all available input source types |\n\n### Filters (7 tools)\n\n| Tool | Description |\n|------|-------------|\n| `list_source_filters` | List all filters applied to a source |\n| `get_source_filter` | Get filter details and settings |\n| `create_source_filter` | Add a new filter to a source (color correction, noise suppression, etc.) |\n| `remove_source_filter` | Remove a filter from a source |\n| `toggle_source_filter` | Enable/disable a filter |\n| `set_source_filter_settings` | Modify filter configuration |\n| `list_filter_kinds` | List all available filter types |\n\n### Transitions (5 tools)\n\n| Tool | Description |\n|------|-------------|\n| `list_transitions` | List all available transitions and current one |\n| `get_current_transition` | Get current transition details |\n| `set_current_transition` | Change the active transition (Cut, Fade, Swipe, etc.) |\n| `set_transition_duration` | Set transition duration in milliseconds |\n| `trigger_transition` | Trigger studio mode transition (preview to program) |\n\n### Virtual Cam & Replay Buffer (6 tools)\n\n| Tool | Description |\n|------|-------------|\n| `get_virtual_cam_status` | Check if virtual camera output is active |\n| `toggle_virtual_cam` | Toggle virtual camera on/off |\n| `get_replay_buffer_status` | Check if replay buffer is active |\n| `toggle_replay_buffer` | Toggle replay buffer on/off |\n| `save_replay_buffer` | Save current replay buffer to file |\n| `get_last_replay` | Get the file path of the last saved replay |\n\n### Studio Mode & Hotkeys (6 tools)\n\n| Tool | Description |\n|------|-------------|\n| `get_studio_mode_enabled` | Check if studio mode is enabled |\n| `toggle_studio_mode` | Enable or disable studio mode |\n| `get_preview_scene` | Get the current preview scene (studio mode) |\n| `set_preview_scene` | Set the preview scene (studio mode) |\n| `list_hotkeys` | List all available OBS hotkeys |\n| `trigger_hotkey_by_name` | Trigger a hotkey by name |\n\n### Meta Tools (4 tools, always enabled)\n\n| Tool | Description |\n|------|-------------|\n| `help` | Get detailed help on tools, resources, prompts, workflows, or troubleshooting |\n| `get_tool_config` | Query current tool group configuration (enabled/disabled state) |\n| `set_tool_config` | Enable/disable tool groups at runtime (session-only or persistent) |\n| `list_tool_groups` | List all tool groups with descriptions and status |\n\n**Example: Disable Visual tools for a lighter setup**\n```json\n{\n  \"tool\": \"set_tool_config\",\n  \"arguments\": {\n    \"group\": \"Visual\",\n    \"enabled\": false,\n    \"persist\": true\n  }\n}\n```\n\n**Total: 81 tools in 9 groups** (Core, Sources, Audio, Layout, Visual, Design, Filters, Transitions, Automation) + Meta (4 always-enabled tools)\n\n## MCP Resources\n\nThe server exposes OBS data as MCP resources for efficient access and monitoring:\n\n| Resource Type | URI Pattern | Content Type | Description |\n|---------------|-------------|--------------|-------------|\n| Scenes | `obs://scene/{name}` | `obs-scene` (JSON) | Scene configuration with sources and settings |\n| Screenshots | `obs://screenshot/{name}` | `image/png` or `image/jpeg` | Binary screenshot images from capture sources |\n| Screenshot URLs | `obs://screenshot-url/{name}` | `text/plain` | HTTP URL for screenshot image access |\n| Presets | `obs://preset/{name}` | `obs-preset` (JSON) | Scene preset configurations with source visibility |\n\n**Usage:**\n- `resources/list` - List all available resources\n- `resources/read` - Get detailed resource content\n- Resources support notifications for real-time updates\n- **Completions**: Autocomplete available for resource URI names\n\n## MCP Prompts\n\nPre-built workflow prompts guide AI assistants through common OBS tasks:\n\n| Prompt | Arguments | Purpose |\n|--------|-----------|---------|\n| `stream-launch` | none | Pre-stream checklist and setup |\n| `stream-teardown` | none | End-stream cleanup workflow |\n| `audio-check` | none | Audio verification and diagnostics |\n| `visual-check` | screenshot_source | Visual layout analysis |\n| `health-check` | none | Comprehensive OBS diagnostics |\n| `problem-detection` | screenshot_source | Automated issue detection |\n| `preset-switcher` | preset_name (optional) | Scene preset management |\n| `recording-workflow` | none | Recording session guidance |\n| `scene-organizer` | none | Scene organization and cleanup |\n| `quick-status` | none | Brief status summary |\n| `scene-designer` | scene_name, action (optional) | Visual layout creation with Design tools |\n| `source-management` | scene_name | Manage source visibility and properties |\n| `visual-setup` | monitor_scene (optional) | Configure screenshot monitoring |\n| `automation-setup` | rule_type (optional), trigger_event (optional) | Create and manage automation rules (FB-20) |\n\nPrompts combine multiple tools into cohesive workflows with best practices built-in.\n**Completions**: Autocomplete available for prompt arguments (preset names, screenshot sources, scene names).\n\n## Development\n\n### Project Structure\n\n```\nagentic-obs/\n├── main.go                 # Entry point (MCP server or TUI)\n├── config/                 # Configuration management\n├── internal/\n│   ├── mcp/               # MCP server implementation (81 tools)\n│   ├── obs/               # OBS WebSocket client\n│   ├── storage/           # SQLite persistence\n│   ├── http/              # HTTP server for screenshots and dashboard\n│   ├── screenshot/        # Background capture manager\n│   └── tui/               # Terminal UI dashboard\n├── skills/                 # Claude Skills packages\n└── scripts/               # Development helpers\n```\n\n### Adding a New Tool\n\n1. Define tool schema in `internal/mcp/tools.go`\n2. Implement handler function\n3. Register tool in server initialization\n4. Add OBS command wrapper in `internal/obs/commands.go` if needed\n\n### Running Tests\n\n```bash\ngo test ./...\n```\n\n## Configuration\n\nConfiguration is stored in SQLite (`agentic-obs.db`) and includes:\n\n- OBS WebSocket connection details (host, port, password)\n- Scene and source presets\n- User preferences\n\n## Troubleshooting\n\n### Connection Issues\n\n**Problem**: \"Failed to connect to OBS\"\n\n**Solutions**:\n- Ensure OBS Studio is running\n- Verify WebSocket server is enabled in OBS (Tools → WebSocket Server Settings)\n- Check that port 4455 is not blocked by firewall\n- Confirm password matches if authentication is enabled\n\n### Permission Issues\n\n**Problem**: Database write errors\n\n**Solutions**:\n- Ensure the directory is writable\n- Check file permissions on `agentic-obs.db`\n\n## Claude Skills\n\nThe `skills/` directory contains shareable Claude Skills packages that teach AI assistants how to orchestrate agentic-obs tools effectively:\n\n| Skill | Purpose |\n|-------|---------|\n| `streaming-assistant` | Complete streaming workflows (pre-stream, live, teardown) |\n| `scene-designer` | Visual layout creation with 14 Design tools |\n| `audio-engineer` | Audio optimization and troubleshooting |\n| `preset-manager` | Preset lifecycle and organization |\n\nSkills use progressive disclosure for token-efficient guidance. See `skills/README.md` for installation.\n\n## Future Enhancements\n\n- Automation rules and macros\n- Multi-instance OBS support\n- Real-time event notifications\n- Additional resource types (filters, transitions)\n\n## Contributing\n\nContributions are welcome! Please open an issue or submit a pull request.\n\n## License\n\n[Add your license here]\n\n## Resources\n\n- [Model Context Protocol](https://modelcontextprotocol.io)\n- [OBS WebSocket Protocol](https://github.com/obsproject/obs-websocket)\n- [goobs Library](https://github.com/andreykaipov/goobs)\n\n---\n\n**Built with:**\n- Go 1.25.5\n- MCP Go SDK v1.1.0\n- goobs v1.5.6\n- bubbletea/lipgloss (TUI)\n"}