obsbot-mcp

A cross-platform Model Context Protocol server that controls an OBSBOT Tiny 2 camera over its standard UVC/USB interface — pan/tilt/roll the gimbal, zoom, AI subject tracking, focus/exposure/white-balance/image controls, HDR and field-of-view, plus snapshot, preview, and recording — without any vendor SDK.

Install

npm install obsbot-mcp

MCP client configuration

Add a stdio server entry pointing at the installed binary (or directly at dist/index.js):

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

If you're running from a local checkout instead of an npm install, point command/args at node and the built entry point instead:

{
  "mcpServers": {
    "obsbot": {
      "command": "node",
      "args": ["path/to/obsbot-mcp/dist/index.js"]
    }
  }
}

Debug / diagnostics tools

By default the server advertises only the normal control surface. Pass --debug to additionally expose the diagnostics surface — the obsbot_debug_probe tool (raw XU byte get/set/query) and the raw 60-byte status block on obsbot_status:

{
  "mcpServers": {
    "obsbot": {
      "command": "node",
      "args": ["path/to/obsbot-mcp/dist/index.js", "--debug"]
    }
  }
}

With the installed binary, use "command": "obsbot-mcp" and "args": ["--debug"].

Tools

35 tools on Windows and macOS, 34 on Linux (obsbot_gimbal_move_speed is unavailable there — see limitations). --debug adds obsbot_debug_probe for one more. All names below are current as of v0.4.0 — every tool was renamed in this release and there is no backward-compatible alias; see CHANGELOG.md for the full old→new mapping if you're updating a caller.

The camera selector

Every camera-addressing tool accepts an optional camera parameter: the target camera's serial number. Omit it with a single camera attached and nothing changes — this matches the server's pre-v0.4.0, single-camera behaviour exactly. With more than one camera attached, a call that omits camera fails with an error naming every attached serial, so you always know what to pass next.

Exempt (no camera parameter, ever): obsbot_devices (enumerates the whole fleet), obsbot_capture_stop / obsbot_capture_list (address a sessionId, not a device), and obsbot_debug_probe (operates on the current diagnostics transport). Two more tools honor it only partially — see Capture below.

Multi-camera support is new in v0.4.0. It's exercised by the unit test suite against fakes; running two physical Tiny 2s at once has not yet been hardware-verified (see Known limitations).

obsbot_devices is the way to discover the serials you pass as camera: it reports each attached camera's serial (where obtainable — reading it requires briefly opening the camera), name, and status (available | bound | busy). A camera another process already holds comes back busy with no serial, since it can't be opened to read one.

Device & power

Gimbal (PTZ)

Aiming at what you can see

obsbot_capture_snapshot returns the frame as an image plus its width/height, so a model can locate something in the picture and then point the camera at it:

1. obsbot_capture_snapshot — look at the frame
2. obsbot_aim_at_pixel — pass the target's pixel and that frame's dimensions
3. obsbot_capture_snapshot again — confirm it landed, and repeat if needed

Pass the frameWidth/frameHeight from the same snapshot the pixel came from. Mixing a pixel from one frame with dimensions from another aims at the wrong place, and nothing can detect it.