raveendiranrr/obs_studio_mcp repository overview

⁠OBS Studio MCP for Docker

Control OBS Studio from an AI agent using the Model Context Protocol (MCP). This image packages royshil/obs-mcp⁠ and exposes tools for scenes, sources, webcam layouts, audio, streaming, recording, and more through OBS WebSocket.

This image runs the MCP connector, not OBS Studio. Install and run OBS separately, either on your computer or in another container. The image does not provide an OBS desktop or an HTTP MCP endpoint.

⁠Purpose

Use an MCP-compatible agent to automate OBS production tasks:

• Create scenes and arrange a webcam alongside a screen capture.
• Switch scenes, configure transitions, and toggle source visibility.
• Adjust input volume, mute microphones, and configure filters.
• Start, pause, resume, or stop recordings.
• Control streaming, the replay buffer, and the virtual camera.
• Inspect OBS status and capture screenshots for layout verification.

The agent translates your request into tool calls. OBS performs the actual capture, rendering, recording, and streaming on the machine where OBS runs.

⁠Requirements

• Docker installed and running, with docker available to your IDE.
• OBS Studio with OBS WebSocket v5 enabled. WebSocket is bundled with OBS Studio 28 and later; individual tools may require newer OBS versions or plugins.
• An MCP client that can launch a local command using stdio.
• Network connectivity from the MCP container to OBS.
• Docker MCP Toolkit for the Toolkit option below. The profile commands shown are documented for Docker Desktop 4.62 and later.

V1 is ARM64, suitable for Apple Silicon and other ARM64 Docker hosts. It is not a multi-platform release. For native AMD64 support, build an AMD64 image from this repository.

⁠Enable OBS WebSocket

1. Launch OBS Studio.
2. Open Tools > WebSocket Server Settings.
3. Check Enable WebSocket server.
4. Leave Server Port at 4455, unless you need another port.
5. Keep Enable Authentication checked and generate or set a password.
6. Click Apply, then OK, and leave OBS running.

On macOS, grant OBS the camera, microphone, and screen recording permissions required by your sources. Connect your camera and enable the display you want to capture. A laptop's built-in display may be unavailable while its lid is closed.

See the official OBS WebSocket documentation⁠.

⁠Pull the Image

docker pull raveendiranrr/obs_studio_mcp:V1

The tag is case-sensitive: use V1.

⁠Option 1: Docker MCP Toolkit

⁠Register the server

The repository includes docker-mcp.yaml⁠, configured to use the published image. From the repository directory, run these commands in a macOS or Linux shell:

mkdir -p ~/.docker/mcp/catalogs
cp docker-mcp.yaml ~/.docker/mcp/catalogs/obs-mcp.yaml
docker mcp profile server add default --server file://obs-mcp.yaml

If you only have the image, create obs-mcp.yaml in ~/.docker/mcp/catalogs/ with the following content, then run the registration command above:

name: obs-mcp
title: OBS Studio
type: server
image: raveendiranrr/obs_studio_mcp:V1
description: Control OBS Studio through OBS WebSocket using MCP.
allowHosts:
  - host.docker.internal:4455
env:
  - name: OBS_WEBSOCKET_URL
    value: "{{obs-mcp.websocket_url}}"
  - name: OBS_WEBSOCKET_PASSWORD
    value: "{{obs-mcp.websocket_password}}"
config:
  - name: obs-mcp
    description: OBS WebSocket connection settings.
    type: object
    properties:
      websocket_url:
        type: string
        default: ws://host.docker.internal:4455
      websocket_password:
        type: string
        default: ""

These examples assume a profile ID of default. Check with docker mcp profile list. If that ID does not exist, create it with docker mcp profile create --name default, or substitute an existing ID throughout the examples.

⁠Configure the connection

For OBS on the same computer as Docker Desktop:

docker mcp profile config default --set obs-mcp.websocket_url=ws://host.docker.internal:4455
docker mcp profile config default --set 'obs-mcp.websocket_password="REPLACE_WITH_OBS_PASSWORD"'

Replace the password locally. The inner double quotes encode a JSON string; the outer single quotes protect it from the shell. Keep this structure even for numeric passwords, which Docker otherwise interprets as numbers. Passwords containing double quotes or backslashes require JSON escaping. Do not publish credentials or commit configured passwords.

If OBS authentication is disabled, set an explicit empty string:

docker mcp profile config default --set 'obs-mcp.websocket_password=""'

The profile stores configuration, including the password. Treat it as sensitive and prefer password-protected OBS access for normal use.

⁠Discover and test tools

docker mcp profile server ls --filter profile=default
docker mcp tools ls --gateway-arg=--profile --gateway-arg=default
docker mcp tools call --gateway-arg=--profile --gateway-arg=default obs-get-status
docker mcp tools call --gateway-arg=--profile --gateway-arg=default obs-test-connection

Tool discovery confirms that the MCP server starts, not that OBS is connected. Check that obs-get-status reports connected: true and identified: true. A successful test reports Connection test successful - OBS is responding.

⁠Connect your IDE to the gateway

For clients using the mcpServers JSON format:

{
  "mcpServers": {
    "docker-mcp": {
      "command": "docker",
      "args": ["mcp", "gateway", "run", "--profile", "default"]
    }
  }
}

For VS Code's .vscode/mcp.json format, use a top-level servers object instead and add "type": "stdio" to the entry. The gateway exposes the servers enabled in that profile, not just OBS.

Your IDE launches the gateway; a separate terminal gateway is unnecessary for this setup. Restart or reconnect the MCP server in your IDE after changing settings.

See Docker's MCP Toolkit CLI guide⁠ for profile and gateway commands.

⁠Option 2: Connect an IDE Directly to Docker

This option does not require Docker MCP Toolkit.

⁠Create a private environment file

Create obs-mcp.env outside your repository:

OBS_WEBSOCKET_URL=ws://host.docker.internal:4455
OBS_WEBSOCKET_PASSWORD=REPLACE_WITH_OBS_PASSWORD

Replace the password with the one from OBS. Docker's --env-file passes values literally: do not surround the password with quotation marks. If authentication is disabled, leave the value after = empty. Keep the file out of version control. On macOS/Linux, restrict access with chmod 600 /absolute/path/obs-mcp.env.

⁠Cursor and clients using mcpServers

In Cursor, use .cursor/mcp.json for a project or ~/.cursor/mcp.json for your user. Other clients using mcpServers, such as Claude Desktop, can use the same entry in their own MCP configuration file:

{
  "mcpServers": {
    "obs-studio": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--env-file",
        "/absolute/path/obs-mcp.env",
        "raveendiranrr/obs_studio_mcp:V1"
      ]
    }
  }
}

Replace the file path with a real absolute path. On Windows, a JSON path might be C:\\Users\\YourName\\obs-mcp.env.

⁠VS Code / GitHub Copilot

For VS Code's .vscode/mcp.json format:

{
  "servers": {
    "obs-studio": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--env-file",
        "/absolute/path/obs-mcp.env",
        "raveendiranrr/obs_studio_mcp:V1"
      ]
    }
  }
}

Start the server using VS Code's MCP controls and enable its tools in your agent session. VS Code also supports portable .mcp.json files with a top-level mcpServers object; use the preceding generic example for that format.

⁠Other agentic IDEs

For any client supporting local MCP servers, configure:

Enter arguments as separate array entries when required. Keep -i to preserve standard input; do not add -t or -d. No MCP port mapping is needed because communication uses stdio. If your IDE runs remotely or inside a development container, Docker access, the file path, and the OBS address must be valid in that environment.

After connecting, ask the agent to test its OBS connection before making changes. See the Cursor MCP guide⁠ and VS Code MCP guide⁠ for client details.

⁠Network Configuration

localhost inside the MCP container refers to that container, not your computer. If Toolkit network blocking is enabled, update the catalog's allowHosts to match a custom OBS host and port. An OBS container needs its own camera, audio, and display capture setup.

Media paths, recording directories, and screenshot save paths refer to the filesystem where OBS runs, not the MCP container or IDE. Mount media into the OBS container if OBS itself is containerized.

⁠Available Tools

V1 registers 127 tools across 13 categories. Support depends on your OBS version, plugins, platform, and devices. See OBS_MCP_TOOLS.md⁠ for the complete names. Your client discovers each tool's description and argument schema through MCP.

For individual schemas in Toolkit:

docker mcp tools inspect --gateway-arg=--profile --gateway-arg=default obs-create-scene

⁠Example Agent Requests

• "Test the OBS connection and list my scenes."
• "Create a scene called Demo with my webcam on the left and my laptop display on the right. Confirm the devices before configuring them."
• "Mute my microphone and show the recording status."
• "Save a screenshot of the Demo scene so I can check its layout."
• "Switch to the Presentation scene using a fade transition."

Device and source names must match what OBS exposes. Creating a scene does not guarantee that devices are connected or capture permissions are granted.

⁠Troubleshooting

A manually started container may appear idle while waiting for MCP messages. The IDE normally starts and manages it; it is not a browser-accessible service.

⁠Build from Source

From this repository directory:

docker build -t obs-mcp:local .

For an AMD64 image:

docker buildx build --platform linux/amd64 --load -t obs-mcp:local .

Use obs-mcp:local in your IDE configuration or catalog when using a local build. The Dockerfile compiles TypeScript and runs the server as the non-root node user.

⁠Environment Variables

Outside this image, the upstream server defaults to ws://localhost:4455. The image overrides that default for Docker Desktop host access.

⁠Attribution and License

This image packages royshil/obs-mcp⁠. Credit for the upstream MCP server belongs to its author and contributors. V1 is the Docker image release tag, separate from the upstream server version.

The repository includes the GNU General Public License, version 2. See LICENSE⁠ for full terms. Third-party components retain their respective licenses. Preserve the license and attribution when redistributing this project.

⁠Disclaimer

This is an independent community image. It is not affiliated with, endorsed by, or officially supported by the OBS Project, Docker, or any IDE or AI provider. Product names and trademarks belong to their respective owners.

The software is provided as is, without warranty, subject to the included license. Availability and behavior depend on OBS, its plugins, your devices, your MCP client, and network connectivity.

An agent with these tools can start or stop live broadcasts and recordings, change scenes, remove sources, alter audio, and capture screen or camera content. Review agent actions before granting approval, back up important OBS profiles and scene collections, and test workflows before live production. The connector does not add a per-action approval layer; approval behavior comes from your MCP client.

Keep WebSocket authentication enabled, protect credentials, and restrict access to trusted clients and networks. You are responsible for captured or broadcast content and for obtaining necessary permissions or consent. To the extent allowed by applicable law and the license, authors and distributors disclaim liability for loss, unintended broadcasts, recording failures, or other consequences of use.