Obsbot MCP

What lxman/obsbot-mcp does

lxman/obsbot-mcp gives MCP-compatible clients control of an OBSBOT Tiny 2 connected over USB. It communicates through standard UVC controls and OBSBOT's vendor protocol directly, so it does not depend on a vendor SDK or cloud service. The package includes native helpers for Windows, macOS, and Linux.

The server exposes 35 tools on Windows and macOS, and 34 on Linux. Its controls cover camera discovery, wake and sleep, gimbal movement, zoom, AI subject tracking, focus, exposure, white balance, HDR, field of view, image adjustments, presets, and snapshot capture.

How it works

Install the npm package and run it as a stdio MCP server. An MCP client sends tool calls to the process, which communicates with the attached camera. When multiple cameras are present, use obsbot_devices to discover the serial value accepted by camera-addressing tools. Calls can omit the camera selector when only one camera is attached.

Gimbal coordinates use degrees: positive yaw moves toward the camera's left, and positive pitch tilts downward. Wake and sleep are physical actions. Waking unstows the gimbal and returns it near level; sleeping stows it face-down at approximately 84 degrees of pitch.

Snapshot-based framing requires data from the same obsbot_capture_snapshot result. obsbot_aim_at_pixel uses that frame's pixel coordinates and dimensions, while obsbot_zoom_to_fit uses a region and adds an optional margin. Both tools account for the camera's reported field of view and zoom state before moving.

Setup and configuration

Install the package with npm:

npm install obsbot-mcp

Configure the MCP client to launch the installed executable over stdio:

{
  "mcpServers": {
    "obsbot": {
      "command": "obsbot-mcp"
    }
  }
}

A local checkout can instead launch the built entry point with Node.js. Passing --debug adds the obsbot_debug_probe diagnostic tool and includes the raw 60-byte status block in obsbot_status responses.

Tools and capabilities

• Discover attached OBSBOT cameras and inspect whether each is available, bound, or busy.
• Wake, sleep, recenter, move, and read the position of the gimbal.
• Set UVC zoom or use the vendor zoom path with a selectable speed.
• Enable AI tracking, select human-framing or scene modes, and choose standard or sport tracking speed.
• Switch autofocus or manual focus, adjust exposure, white balance, HDR, field of view, and supported image controls.
• Save, update, rename, recall, list, and delete three gimbal preset slots.
• Capture still images and use them for pixel aiming or region-to-frame zooming.

Limitations and notes

The Tiny 2's gimbal and zoom actions can take time to settle. Recenter and preset recall may return before motion finishes, and zoom operations report whether the requested position settled. Poll position or status when subsequent actions depend on the final pose.

AI tracking and frame-based aiming are mutually exclusive. Aiming also refuses stale or unsafe conditions, including a camera that had to wake, an undecodable field of view, an implausible zoom reading, or a target that would require an over-the-top rotation. A virtual or NDI source must be an unmodified pass-through of the camera feed for its geometry to remain correct.

The Tiny 2 supports brightness, contrast, hue, saturation, and sharpness through the image-adjustment tool. Gain and backlight compensation are rejected because the camera exposes those controls as zero-length controls. Manual focus positions use a 0-100 near-to-far scale; status reports a focus position only in manual mode.

On Linux, the speed-based gimbal movement tool is unavailable, and gimbal position feedback represents the last commanded value rather than live in-flight motion. Multi-camera support is exercised in tests, while simultaneous use of multiple physical Tiny 2 cameras has not been hardware-verified.