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

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

License

MIT License - see LICENSE for details.