OBSBOT Tiny 2 Camera Control

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. It also controls the OBSBOT Tail 2 network camera over its HTTP/WS API (see OBSBOT Tail 2 below).

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. Every Tail 2 camera on the network adds the 48 obsbot_tail2_* tools in OBSBOT Tail 2 below (all platforms — they are pure TypeScript). 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.

The snapshot must be `source: "device"`. obsbot_capture_snapshot can also read from source: "virtual" or "ndi", which come from OBSBOT Center's own output rather than the camera's raw stream. Those are framed and cropped by OBSBOT Center, not by this camera's optics, so the measured field-of-view constants this tool relies on don't describe them — aiming from a virtual or NDI frame lands in the wrong place with no way to detect it. Only use a device-source snapshot's pixel and dimensions here.

The tool reads the camera's magnification itself — a discrete FOV mode or a continuous zoom alike (m = 3*ratio-2, measured on hardware to better than 0.05%) — so there is no FOV or zoom argument to get wrong, and it works at any zoom. It refuses rather than guessing when AI tracking is on (tracking drives the gimbal and would fight the aim), when the FOV mode can't be decoded, when a corrupt zoom reading would resolve to an implausible magnification, or when the camera had to be woken from sleep (waking moves the gimbal, so the frame you measured no longer matches where the camera is pointing — take a fresh snapshot and retry).

Framing what you can see

obsbot_zoom_to_fit extends the same idea from a point to a region: instead of just centring on a pixel, it also zooms so that region fills the frame.

1. obsbot_capture_snapshot — look at the frame
2. Pick a bounding box around whatever should fill the frame (a face, a whiteboard, ...)
3. obsbot_zoom_to_fit — pass the box (x, y, width, height) and that frame's dimensions
4. obsbot_capture_snapshot again — confirm the framing, and repeat if needed

It shares obsbot_aim_at_pixel's refusals (AI tracking, undecodable FOV/zoom, a woken camera, a zoom still ramping, a non-16:9 frame), and adds one of its own: the region must lie within the frame — edges included, so a region that already IS the full frame is valid — with a positive width and height, or the call refuses rather than guess what a negative width or an