OBS MCP Composer

obs-mcp-composer is a TypeScript MCP server for OBS Studio that treats OBS like a broadcast canvas, not just a remote control target.

It handles the usual operational tasks you expect from an OBS integration, like scene switching, audio control, recording, streaming, transitions, and screenshots. The part that makes it more useful for AI workflows is the composition layer on top: scene item positioning, overlay construction, browser-driven panels, chat placement, framed webcam layouts, and a structured scene builder that can assemble a full scene from JSON.

The goal is simple: give an AI enough leverage to build and rearrange broadcast layouts, not just poke a few buttons.

Features

OBS connection over obs-websocket-js
MCP stdio transport for local MCP clients
Scene management: list, create, switch, duplicate, remove
Scene item control: enable, move, resize, rotate, duplicate, reorder, remove
Input management for text, image, and browser sources
Audio controls for mute and volume
Stream and recording controls
Transition and filter controls
Source and scene screenshots
Layout helpers for centering, alignment, anchoring, and bounds-based resizing
Composition helpers for text overlays, panels, chat overlays, webcam framing, grouping, and layout duplication
build_scene_from_spec for structured scene creation from JSON
Normalized JSON error responses for common OBS connection and lookup failures
Lightweight logging to stderr so MCP stdout stays clean

Setup

1. Install dependencies

npm install

2. Make sure OBS websocket is enabled

OBS Studio 28+ ships with obs-websocket built in.

In OBS:

Open Tools -> WebSocket Server Settings
Enable the websocket server
Note the host, port, and password

The defaults are usually:

host: 127.0.0.1
port: 4455

3. Configure environment variables

Copy .env.example to .env and fill in your OBS connection details:

OBS_HOST=127.0.0.1
OBS_PORT=4455
OBS_PASSWORD=your-obs-websocket-password
LOG_LEVEL=info

Required variables:

OBS_HOST
OBS_PORT
OBS_PASSWORD

4. Build the server

npm run build

5. Run the server

For local testing:

npm start

For development:

npm run dev

This server uses MCP stdio transport, so in a real MCP client you would typically point the client at:

node dist/index.js

Example Usage

The exact MCP client UX depends on the host, but these examples show the tool inputs the server expects.

Check that OBS is reachable

Tool: obs_ping

{}

Switch scenes

Tool: set_scene

{
  "sceneName": "Gameplay"
}

Create a browser chat overlay

Tool: place_chat_overlay

{
  "sceneName": "Live",
  "url": "https://example.com/chat",
  "x": 1520,
  "y": 180,
  "width": 360,
  "height": 760,
  "anchor": "top-left"
}

Create a lower third

Tool: create_lower_third

{
  "sceneName": "Interview",
  "title": "Alex Rivera",
  "subtitle": "Technical Director",
  "accentColor": "#111827",
  "textColor": "#ffffff"
}

Build a full scene from a spec

Tool: build_scene_from_spec

{
  "sceneName": "Starting Soon",
  "replaceExisting": true,
  "theme": {
    "backgroundColor": "#0b1020",
    "accentColor": "#8b5cf6",
    "textColor": "#ffffff"
  },
  "elements": [
    {
      "type": "text",
      "text": "Starting Soon",
      "fontSize": 72,
      "color": "#ffffff",
      "x": 960,
      "y": 220,
      "anchor": "center"
    },
    {
      "type": "browser",
      "name": "chat",
      "url": "https://example.com/chat",
      "x": 1510,
      "y": 180,
      "width": 360,
      "height": 760
    },
    {
      "type": "panel",
      "name": "status-bar",
      "color": "#8b5cf6",
      "opacity": 0.18,
      "x": 120,
      "y": 820,
      "width": 920,
      "height": 140
    }
  ]
}

The server will:

create or rebuild the target scene
optionally lay down a background panel from the theme
create the required inputs
place them on the canvas
return a summary of what was created

Tool Overview

Health / system

obs_ping
obs_get_version
obs_get_stats

Scenes

list_scenes
get_current_scene
set_scene
create_scene
duplicate_scene
remove_scene

Scene items

list_scene_items
set_scene_item_enabled
set_scene_item_transform
set_scene_item_index
duplicate_scene_item
remove_scene_item

Inputs / sources

list_inputs
create_text_input
create_image_input
create_browser_input
set_input_settings
remove_input

Audio

get_input_mute
set_input_mute
toggle_input_mute
get_input_volume
set_input_volume

Outputs

start_stream
stop_stream
start_recording
stop_recording
get_stream_status

Transitions

list_transitions
set_transition
set_transition_duration

Filters

list_filters
set_filter_enabled
set_filter_settings

Screenshots

get_scene_screenshot
get_source_screenshot

Layout

center_source
align_source
anchor_source
resize_source_to_bounds

Composition

create_overlay_text_block
create_overlay_panel
place_webcam_frame
place_chat_overlay
group_sources
duplicate_layout

Workflows

build_scene_from_spec
create_lower_third

Project Structure

src/
  index.ts          Entry point, env loading, stdio transport
  server.ts         MCP server construction and tool registration
  types.ts          Shared project types and scene spec types
  obs/
    client.ts       OBS websocket connection and convenience helpers
    errors.ts       Normalized error mapping
  tools/
    ...             Domain-oriented MCP tool modules
  utils/
    validation.ts   Shared validation and layout helpers
    responses.ts    MCP tool response wrapper
    logger.ts       Small stderr logger

The code is intentionally organized by problem domain instead of by protocol layer. Low-level OBS calls live in the client, tool modules stay readable, and the composition/workflow layer can build on the same primitives instead of duplicating logic.

Notes

OBS source kinds are not perfectly uniform across platforms. Text input creation tries to pick a reasonable available text source kind for the local OBS install.
group_sources is implemented using a dedicated scene that can be nested elsewhere. That maps well to how OBS handles reusable layout groupings.
The higher-level overlay tools use browser sources where that produces more predictable visual results, especially for panels and styled text.
The server returns JSON-shaped MCP responses so downstream agents can inspect success and failure states cleanly.

Future Ideas

More layout presets for side-by-side interview scenes, scoreboards, and countdown packages
Scene collection helpers
Safer upsert semantics for existing overlays and inputs
Optional asset templates for branded lower thirds and sponsor panels
Smarter text-source styling per platform and OBS version

MCP Servers