OBS Controller MCP Server

MCP server for controlling OBS Studio via WebSocket API. Provides 100+ tools for complete OBS automation through Claude Code or any MCP-compatible client.

Features

• Full OBS Control - Manage scenes, sources, inputs, filters, and transitions
• Streaming & Recording - Start/stop streams and recordings, manage replay buffer
• Audio Management - Control volume, mute, audio tracks, and monitoring
• Media Playback - Play, pause, stop, and seek media sources
• Studio Mode - Full support for preview/program workflow
• Performance Monitoring - Access OBS stats and video settings

Tool Categories

Category	Description	Tools
Scenes	Create, switch, and manage scenes	12
Inputs	Control sources, settings, and audio	25
Streaming	Stream control and service settings	8
Recording	Record, pause, chapters, and directory	10
Transitions	Manage scene transitions	10
Filters	Add/remove/configure source filters	10
Scene Items	Position, transform, visibility	15
Media	Playback control for media sources	8
Outputs	Virtual camera, replay buffer	12
General	Stats, hotkeys, profiles	10+

Installation

From PyPI (Recommended)

pip install obs-controller

From Source

git clone https://github.com/ldraney/obs-controller
cd obs-controller
poetry install

Quick Start

1. Enable OBS WebSocket - In OBS: Tools > WebSocket Server Settings > Enable
2. Configure connection - Set environment variables (see Configuration below)
3. Run the MCP server:

   # If installed from PyPI
   obs-controller
   
   # If installed from source
   poetry run python -m obs_controller.server

Configuration

Set environment variables or create a .env file:

OBS_HOST=172.25.128.1  # Windows host IP from WSL
OBS_PORT=4455
OBS_PASSWORD=          # If authentication enabled
OBS_TIMEOUT=10

Claude Code Integration

Using PyPI Installation

claude mcp add obs-controller -- obs-controller

Using Source Installation

claude mcp add obs-controller -- poetry --directory /path/to/obs-controller run python -m obs_controller.server

Example Usage

Once integrated with Claude Code, you can control OBS with natural language:

> Switch to the "Gaming" scene
> Start recording
> Mute the microphone
> Take a screenshot of the current scene
> What's the current stream status?

Troubleshooting (WSL Users)

Finding Windows Host IP

From WSL, get your Windows host IP:

cat /etc/resolv.conf | grep nameserver | awk '{print $2}'

OBS WebSocket Connection Refused

1. Ensure OBS WebSocket Server is enabled (Tools > WebSocket Server Settings)
2. Check Windows Firewall allows connections on port 4455
3. Verify the host IP is correct in your .env file

Authentication Errors

If you've set a password in OBS WebSocket settings, add it to your .env:

OBS_PASSWORD=your_password_here

Related Projects

• claude-chat-overlay - iPhone Messages-style chat overlay for OBS. Display real-time conversations between you and Claude on stream. Works great with obs-controller to add the browser source automatically.
• twitch-events-overlay - Standalone Twitch events/alerts overlay using EventSub. Displays animated alerts for follows, subs, raids, and cheers.

License

MIT License - see LICENSE for details.