Metadata-Version: 2.4
Name: obs-controller
Version: 0.1.0
Summary: MCP server for controlling OBS Studio via WebSocket API
License: MIT
License-File: LICENSE
Keywords: obs,obs-studio,mcp,websocket,streaming,automation,claude
Author: ldraney
Requires-Python: >=3.10,<4.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: System :: Networking
Requires-Dist: fastmcp (>=2.0.0,<3.0.0)
Requires-Dist: obsws-python-mcp (>=1.8.1,<2.0.0)
Requires-Dist: pydantic (>=2.0,<3.0)
Requires-Dist: pydantic-settings (>=2.0,<3.0)
Requires-Dist: python-dotenv (>=1.0.0,<2.0.0)
Project-URL: Bug Tracker, https://github.com/ldraney/obs-controller/issues
Project-URL: Homepage, https://github.com/ldraney/obs-controller
Project-URL: Repository, https://github.com/ldraney/obs-controller
Description-Content-Type: text/markdown

# OBS Controller MCP Server

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)

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

```bash
poetry install
```

## Quick Start

1. **Enable OBS WebSocket** - In OBS: Tools > WebSocket Server Settings > Enable
2. **Configure connection** - Create `.env` file (see Configuration below)
3. **Test connectivity**:
   ```bash
   poetry run python scripts/hello_obs.py
   ```
4. **Run the MCP server**:
   ```bash
   poetry run python -m obs_controller.server
   ```

## Configuration

Set environment variables or create a `.env` file:

```bash
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

Add to `~/.claude.json` via:
```bash
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:
```bash
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`:
```bash
OBS_PASSWORD=your_password_here
```

## License

MIT License - see [LICENSE](LICENSE) for details.

