Metadata-Version: 2.4
Name: obs-studio-mcp
Version: 0.4.0
Summary: MCP server for controlling OBS Studio over obs-websocket v5: scenes, sources, audio, streaming, recording, replay buffer, stats, and text overlays.
Project-URL: Homepage, https://github.com/aaronckj/obs-studio-mcp
Project-URL: Issues, https://github.com/aaronckj/obs-studio-mcp/issues
Author: aaronckj
License-Expression: MIT
License-File: LICENSE
Keywords: mcp,model-context-protocol,obs,obs-studio,obs-websocket,streaming
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Requires-Dist: mcp<2,>=1.2
Requires-Dist: obsws-python>=1.7
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# obs-studio-mcp

An MCP (Model Context Protocol) server for controlling OBS Studio over
**obs-websocket v5**: scenes, sources, audio, text overlays, streaming,
recording, replay buffer, virtual camera, and performance stats.

- Talks to the obs-websocket server built into OBS 28+ (Tools → WebSocket
  Server Settings).
- Every mutating tool accepts `dry_run=true` and returns a preview instead
  of acting — useful guard rails when an agent drives your live stream.
- No secrets in this repo or in your MCP client config.

## Quick start

1. In OBS: **Tools → WebSocket Server Settings** → enable, note the port
   (default 4455) and password.
2. Provide connection settings via environment:

```bash
export OBS_MCP_HOST=127.0.0.1     # default
export OBS_MCP_PORT=4455          # default
export OBS_MCP_PASSWORD=yourpass  # via the default env backend
```

3. Add to your MCP client:

```bash
# Claude Code
claude mcp add obs -s user -- uvx obs-studio-mcp
```

## Tools

| Area | Tools |
|---|---|
| Scenes | `list_scenes`, `switch_scene`, `set_preview_scene`, `trigger_transition`, `set_studio_mode`, `list_scene_items`, `set_scene_item_visibility` |
| Sources | `list_inputs`, `get_audio_levels`, `set_mute`, `set_volume`, `update_text_source`, `screenshot_source`, `media_control` |
| Output | `stream_status`, `start_stream`, `stop_stream`, `record_status`, `start_record`, `stop_record`, `pause_record`, `save_replay`, `set_replay_buffer`, `set_virtual_cam` |
| System | `get_stats`, `list_profiles`, `switch_profile`, `list_scene_collections`, `switch_scene_collection`, `trigger_hotkey`, `health_check` |

`update_text_source` is handy for driving on-stream overlays from an agent —
question-of-the-day, now-playing, countdowns — anything rendered by a Text
source.

## Secret storage

The only secret is the websocket password.

| Backend | Select with | Reads |
|---|---|---|
| `env` (default) | — | `OBS_MCP_PASSWORD` |
| `file` | `OBS_MCP_SECRETS=file` | `~/.config/obs-studio-mcp/credentials.json` (0600) |
| `vaultproxy` | `OBS_MCP_SECRETS=vaultproxy` (+ `VAULTPROXY_URL`) | a Vaultwarden vault via a local vaultproxy HTTP API |

## Development

```bash
pip install -e '.[dev]'
ruff check src tests && pytest
```

Tests are fully offline (fake obs-websocket client).

## License

MIT
