obs_mcp 5.7.1+2

MCP server for controlling OBS Studio via the obs-websocket v5.x protocol.

obs_mcp

MCP Server for OBS Studio
Control OBS Studio via the Model Context Protocol • Built with Dart • WebSocket v5.x

---

A standalone MCP (Model Context Protocol) server for controlling OBS Studio via the obs-websocket v5.x protocol. Built on top of the obs_websocket Dart library, it exposes OBS operations as MCP tools over stdio transport.

Table of Contents

• What's New in v5.7.0
• Quick Start
• MCP Host Configuration
  • Qoder
  • Claude Desktop
  • VS Code
  • OpenCode
• Code Mode
• Features
• AI Agent Skill
• Configuration
• Development Setup
• Testing with MCP Inspector
• License

What's New in v5.7.0

This release adds comprehensive support for OBS WebSocket v5.7.0 features:

Note: Some features (Canvases, Scene Item private settings) require OBS with obs-websocket v5.7.0 or later.

• Canvases: New canvases_list tool to list all configured canvases
• Input Audio Properties: Full control over audio balance, sync offset, monitor type, and audio tracks
• Input Properties Dialog: Access to list property items and button presses
• Scene Items Extended: Access to source names and private settings
• Transitions: Complete transition management including kind listing, configuration, and T-Bar control
• Filters: Full filter lifecycle management (create, remove, rename, configure, reorder)
• Outputs Extended: List all outputs, get/set output status and settings

Quick Start

For end-users: The recommended approach is to globally activate the package (Option 1). This makes the obs_mcp command available on your PATH and is the easiest way to use the MCP server with AI agents like Qoder, Claude Desktop, or VS Code.

For developers: If you need to modify the source code or add new tools, see the Development Setup section below.

Option 1: Global Activation (Recommended for End-Users)

# Activate the package globally (makes the 'obs_mcp' command available)
dart pub global activate obs_mcp

# Set connection details via environment variables (or use a .env file)
export OBS_WEBSOCKET_URL=ws://localhost:4455
export OBS_WEBSOCKET_PASSWORD=your-password

That's it! Configure your AI agent using one of the MCP Host Configuration examples below, and the agent will launch the server automatically.

Code Mode

This server implements code mode, a pattern that pairs a search tool with an execute tool to give AI agents flexible, sandboxed access to complex functionality. Instead of exposing 60+ individual MCP tools directly, the server exposes just two top-level tools:

• search — discover available operations by query, with configurable detail levels ("brief", "detailed", or "full" for complete parameter schemas).
• execute — run JavaScript code that can call any of the 60+ OBS tools via await call_tool('<tool_name>', { params }).

Why Code Mode?

Code mode, popularized by Cloudflare's MCP servers, offers several advantages:

1. Flexibility — Agents can compose multiple tool calls in a single execution, use control flow (loops, conditionals), and handle complex workflows without round-trip overhead.
2. Discoverability — The search tool lets agents find the right operation without memorizing tool names or reading external docs.
3. Sandboxed execution — Code runs in an isolated context with access only to the tools the server explicitly provides.
4. Reduced token overhead — Instead of the LLM reasoning through multiple tool call steps, it can write a single script that the server executes atomically.

This is why the AI Agent Skill included in this package teaches agents the execute + JavaScript pattern — it's the primary way to interact with OBS through this server.

Features

All tools are prefixed with obs_ and organized into the following groups:

Group	Tools	Description
Connection	connect, disconnect, is_connected, send_raw	Manage the WebSocket connection to OBS
General	general_version, general_stats, general_hotkeys, general_trigger_hotkey, general_sleep, general_broadcast_custom_event	Retrieve OBS version/stats, trigger hotkeys, broadcast custom events
Scenes	scenes_list, scenes_group_list, scenes_get_current_program, scenes_set_current_program, scenes_get_current_preview, scenes_set_current_preview, scenes_create	List, switch, and create scenes
Scene Items	scene_items_list, scene_items_group_list, scene_items_get_id, scene_items_get_enabled, scene_items_set_enabled, scene_items_get_locked, scene_items_set_locked, scene_items_set_transform, scene_items_get_source, scene_items_get_private_settings, scene_items_set_private_settings	Query and control items within scenes, including position/scale/rotation/crop and private settings
Inputs	inputs_list, inputs_kind_list, inputs_special, inputs_get_mute, inputs_set_mute, inputs_toggle_mute, inputs_get_volume, inputs_get_settings, inputs_set_settings, inputs_set_name, inputs_create, inputs_remove	Manage audio/video inputs, mute, volume, and settings
Inputs - Audio	inputs_get_audio_balance, inputs_set_audio_balance, inputs_get_audio_sync_offset, inputs_set_audio_sync_offset, inputs_get_audio_monitor_type, inputs_set_audio_monitor_type, inputs_get_audio_tracks, inputs_set_audio_tracks	Control input audio properties: balance, sync offset, monitor type, and audio tracks
Inputs - Properties	inputs_get_properties_list_items, inputs_press_properties_button	Interact with input properties dialog (list items and button presses)
Stream	stream_status, stream_start, stream_stop, stream_toggle, stream_send_caption	Control live streaming and send captions
Record	record_status, record_start, record_stop, record_toggle, record_pause, record_resume, record_toggle_pause	Control recording sessions
Outputs	outputs_virtual_cam_status/toggle/start/stop, outputs_replay_buffer_status/toggle/start/stop/save, outputs_toggle/start/stop, outputs_list, outputs_get_status, outputs_get_settings, outputs_set_settings	Manage virtual camera, replay buffer, and arbitrary outputs
Config	config_record_directory, config_stream_service_settings	Read recording directory and stream service configuration
UI	ui_studio_mode_enabled, ui_set_studio_mode, ui_open_input_properties/filters/interact, ui_monitor_list	Toggle Studio Mode, open input dialogs, list monitors
Transitions	transitions_trigger_studio, transitions_kind_list, transitions_scene_list, transitions_get_current, transitions_set_current, transitions_set_duration, transitions_set_settings, transitions_get_cursor, transitions_set_tbar	Manage scene transitions: list kinds, configure current transition, T-Bar control
Filters	filters_kind_list, filters_list, filters_default_settings, filters_create, filters_remove, filters_rename, filters_get, filters_set_index, filters_set_settings, filters_set_enabled	Manage source filters: create, remove, configure, and reorder
Canvases	canvases_list	List canvases configured in OBS (v5.7.0+)

Code mode is enabled, providing sandbox execution via a search/execute tool pair.

What Can You Do?

Here's a quick example of what AI agents can do with these tools. The code below is passed to the execute tool, which runs it in a sandboxed JavaScript environment:

// Passed to the execute tool:
const scenes = await call_tool('obs_scenes_list', {});
await call_tool('obs_scenes_set_current_program', { sceneName: 'Live Scene' });
await call_tool('obs_record_start', {});

Agents can orchestrate complex OBS workflows — switching scenes, animating sources, controlling audio, managing recordings and streams, and more.

AI Agent Skill

This package includes an obs-mcp skill for AI agents (Qoder, Claude, etc.) in the skills/obs-mcp/ directory. The skill teaches agents how to:

• Invoke OBS tools via the execute + JavaScript pattern
• Discover available tools using search
• Run common workflows (connection checks, source transforms, animations, recording)
• Avoid common pitfalls (server-side vs client-side timing, transform payload shapes)

Agents can install the skill by running skills get after adding this package as a dependency. See pub.dev/packages/skills for details.

Example agent workflow: The skill teaches agents to:

1. Verify connection: await call_tool('obs_is_connected', {})
2. Discover tools: search({ query: "scene items", detail_level: "detailed" })
3. Execute operations via JavaScript in the execute tool
4. Handle errors with try/finally and restore state

See the skill documentation for complete workflows and best practices.

Configuration

Environment variables can be set via the shell or a .env file. The server searches for .env in the following locations (in order): .env, bin/.env, or adjacent to the running script.

Variable	Description	Default
OBS_WEBSOCKET_URL	WebSocket server URL (e.g., ws://localhost:4455)	—
OBS_WEBSOCKET_PASSWORD	Authentication password (omit for anonymous connections)	—
OBS_WEBSOCKET_TIMEOUT	Connection timeout in seconds	120

Development Setup

This section is for developers who want to modify the obs_mcp source code or add new tools.

Prerequisites

• Dart SDK >= 3.8.0
• OBS Studio with obs-websocket v5.x (bundled with OBS 28+)

Running from Source

If you're working on the package locally, you can run the server directly from source instead of using the globally activated version:

cd packages/obs_mcp
dart pub get
dart run bin/obs_mcp_server.dart

Code Generation

The MCP dispatcher (lib/src/obs_mcp_server.mcp.dart) is pre-generated and committed to the repository. You only need to run build_runner if you're modifying the ObsMcpServer class or adding new tools.

If you modify lib/src/obs_mcp_server.dart, regenerate the dispatcher:

dart run build_runner build

This produces lib/src/obs_mcp_server.mcp.dart, which wires up all tool handlers.

Testing with MCP Inspector

The MCP Inspector (@modelcontextprotocol/inspector) is the preferred tool for interactively debugging and testing the server.

1. Install the inspector globally:

   npm install -g @modelcontextprotocol/inspector
   

2. Launch the inspector connected to the server:

   cd packages/obs_mcp
   npx @modelcontextprotocol/inspector dart run bin/obs_mcp_server.dart
   

   Or if you've activated the package globally:

   npx @modelcontextprotocol/inspector obs_mcp
   

3. Browse and invoke tools in the web UI that opens automatically. You can inspect request/response payloads for each tool call.

4. Provide connection credentials by placing a .env file in the packages/obs_mcp/ or packages/obs_mcp/bin/ directory with your OBS_WEBSOCKET_URL and OBS_WEBSOCKET_PASSWORD values.

Contributing

Contributions are welcome! This package is part of the obs_websocket workspace.

Before submitting a PR:

1. Make changes to lib/src/obs_mcp_server.dart (add @Tool annotated methods)
2. Regenerate the dispatcher: dart run build_runner build
3. Run tests: dart test
4. Format code: dart format .

See the workspace README for development setup.

License

MIT — see the LICENSE file for details.