OBS Studio MCP Tools

Control OBS Studio through an MCP agent: inspect status, launch OBS, record, capture the active scene, switch scenes and inspect audio routing. Discover additional operations through a searchable catalog generated from the official OBS WebSocket protocol.

Available on npm, with source and releases on GitHub.

Requires Node.js 24.12+ with npm and OBS Studio 28+ with its WebSocket server enabled under Tools > WebSocket Server Settings.

MCP setup

npx -y --prefer-online mcp-obs-studio-tools@latest mcp

{
  "mcpServers": {
    "obs": {
      "command": "npx",
      "args": ["-y", "--prefer-online", "mcp-obs-studio-tools@latest", "mcp"],
      "env": {
        "OBS_ENV_FILE": "/absolute/path/obs.env"
      }
    }
  }
}

Set the client's startup and tool timeouts to 180 seconds. On Windows, clients requiring an executable extension can use npx.cmd.

Copy .env.example to your selected configuration file and enter the WebSocket settings. Alternatively, append --env-file /absolute/path/obs.env to the command. The aliases -env_file and --env_file are supported.

Related MCP server: obs-mcp-server

Tools

Typical agent workflow:

obs_status({})
obs_auth({ address: "127.0.0.1", port: 4455 })
obs_scenes({})
obs_scene_set({ name: "Camera" })
obs_record_start({})
obs_record_stop({})

Start with status. Use obs_launch when the local application needs starting and obs_auth to configure access. Connection errors return an errorCode and actionable userAction.

For additional operations, search, inspect arguments, retrieve required names/IDs from OBS, then execute:

obs_commands({ query: "volume" })
obs_commands({ name: "SetInputVolume" })
obs_execute({ requests: [{
  requestType: "SetInputVolume",
  requestData: { inputName: "Microphone", inputVolumeDb: -6 }
}] })

Sequences validate all commands before execution and stop on failure by default. Completed changes remain applied. Check status before retrying an interrupted operation.

Configuration

Connection precedence: current obs_auth arguments, process environment, selected env file, built-in defaults. Supplied connection settings are saved to the selected file. Workers reload it for subsequent calls. Executable discovery checks running OBS processes, OBS_EXECUTABLE, standard installation folders and PATH, then saves the verified path.

Outputs include JSON status/results, PNG screenshots and recording file paths. Recent recording dates use ISO 8601 UTC: observed stops are marked completedAt; local recording-directory discovery uses modifiedAt. Audio track assignments describe source routing; recording settings select the output tracks. Enabled scene items describe visibility settings, while audio activity and media playback have their own states.

Worker lifecycle

The stdio wrapper starts a worker on demand and reuses its MCP stdio connection. The worker exits itself after 30 minutes of inactivity; active requests suspend its idle timer. The next request starts another worker. OBS continues running independently.

An npx wrapper starts workers through npx ...@latest, resolving updates at each worker startup. Direct Node.js or installed-binary launches use the same local installation. The wrapper passes through the selected env-file path. Updating the wrapper itself takes effect when its MCP connection restarts.

Local CLI and development

npm ci
node src/cli.js mcp --env-file /absolute/path/obs.env
node src/cli.js --tool-manifest
node src/cli.js --version

A single tool call accepts JSON on stdin:

echo '{"name":"GetVersion"}' | node src/cli.js --execute-tool obs_commands

JavaScript ESM with JSDoc. Run npm run check for type checking and tests, npm run catalog:update to refresh the command catalog, and npm outdated to review dependencies. Dependabot checks npm dependencies weekly. CI checks Windows and Linux.

License

GPL-2.0-only. The bundled command catalog comes from obsproject/obs-websocket; its source revision and license are included in data/. OBS communication uses obs-websocket-js.