# obs-mcp-server

An MCP (Model Context Protocol) server for controlling [OBS Studio](https://obsproject.com/) via the built-in obs-websocket plugin. Lets Claude control your scenes, recording, streaming, audio, and more.

## Requirements

- [OBS Studio](https://obsproject.com/) 28 or later (obs-websocket is built in)
- Node.js 18 or later

## OBS Setup

1. Open OBS Studio
2. Go to **Tools → WebSocket Server Settings**
3. Check **Enable WebSocket server**
4. Set a password (recommended)
5. Note the port (default: `4455`)

## Installation

```bash
npm install
```

Create a `.env` file in the project root:

```env
OBS_WS_URL=ws://localhost:4455
OBS_WS_PASSWORD=your_password_here
```

## Claude Desktop Config

Add the following to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "obs": {
      "command": "node",
      "args": ["C:\\path\\to\\obs-mcp-server\\obs-mcp-server.js"]
    }
  }
}
```

Or use `npx` (no cloning required):

```json
{
  "mcpServers": {
    "obs": {
      "command": "npx",
      "args": ["-y", "obs-mcp-server"],
      "env": {
        "OBS_WS_PASSWORD": "your_password_here"
      }
    }
  }
}
```

## Available Tools

### Status & Scenes
| Tool | Description |
|------|-------------|
| `get_status` | Current scene, streaming state, recording state + timecodes |
| `list_scenes` | List all scenes in the active collection |
| `set_scene` | Switch to a named scene |

### Recording & Streaming
| Tool | Description |
|------|-------------|
| `start_recording` | Start recording |
| `stop_recording` | Stop recording (returns output file path) |
| `toggle_recording` | Toggle recording on/off |
| `start_streaming` | Start streaming |
| `stop_streaming` | Stop streaming |

### Sources
| Tool | Description |
|------|-------------|
| `list_sources` | List all sources in a scene |
| `set_source_visibility` | Show or hide a source |

### Audio
| Tool | Description |
|------|-------------|
| `list_audio_inputs` | List all audio inputs with mute/volume state |
| `set_mute` | Mute or unmute an audio input |
| `toggle_mute` | Toggle mute on an audio input |
| `set_volume` | Set volume (0.0–1.0) on an audio input |

### Canvas
| Tool | Description |
|------|-------------|
| `set_canvas_resolution` | Set base/output resolution and FPS (global per collection) |

### Scene Management
| Tool | Description |
|------|-------------|
| `create_scene` | Create a new empty scene |
| `remove_scene` | Delete a scene |
| `rename_scene` | Rename a scene |

### Scene Collections
| Tool | Description |
|------|-------------|
| `list_scene_collections` | List all collections, show active |
| `set_scene_collection` | Switch to a different collection |
| `create_scene_collection` | Create a new scene collection |

### Profiles
| Tool | Description |
|------|-------------|
| `list_profiles` | List all profiles, show active |
| `set_profile` | Switch to a different profile |
| `create_profile` | Create a new profile |
| `remove_profile` | Delete a profile |

### Misc
| Tool | Description |
|------|-------------|
| `save_screenshot` | Save a screenshot of the current output to disk |

## Notes

- **Canvas resolution** is a global OBS setting — it applies to all scenes in the current collection. Use separate scene collections for different aspect ratios (e.g. 16:9 vs 9:16 for YouTube Shorts).
- **Audio input kinds** default to Windows (`wasapi_*`). On macOS, update the `list_audio_inputs` handler to use `coreaudio_input_capture` / `coreaudio_output_capture`.

## License

MIT