Obsbot MCP Server

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 off-frame box was supposed to mean.

margin (default 0.1, i.e. 10%) backs the requested zoom off by that fraction so the region isn't framed exactly edge-to-edge — some breathing room around it survives small aim/zoom error. The region's two axes rarely need the same zoom to fill the frame; the tool always picks the smaller of the two required magnifications, because zooming to the larger one would fill one axis by cropping the other. The result is clamped to the camera's [1x, 4x] magnification range (reported via clamped) — a region demanding more zoom than the camera has still gets the closest fit available, rather than being refused outright.

The gimbal moves before the zoom is commanded. Zoom re-centres what's already in frame but does not keep a specific pixel under the crosshair as it changes — zooming first can push the region's centre out of frame entirely, which would make the subsequent move aim at a pixel that no longer means what it did when the caller measured it.

Zoom is not instantaneous: on this hardware it ramps toward the commanded value rather than jumping to it, so a status read taken immediately after commanding it can catch it mid-transit (observed: commanding ratio 1.5 read back partway there before settling). obsbot_zoom_to_fit polls for up to 3 seconds waiting for the zoom to arrive and returns settled:false — not an error — if it didn't. A frame captured while the zoom is still moving is at an unknown magnification, so check settled before trusting a follow-up snapshot; a false just means the camera was moving slower than expected, not that anything failed.

Gimbal presets

Three on-device preset slots (1–3). Slots are create-once: obsbot_preset_save requires an empty slot (delete first to reuse one); every other preset tool requires the slot to already be occupied. Each tool re-reads the slot list after writing and returns a structured { ok:false } failure if the device didn't land the change.

Zoom

Two tools, not one — they ride different transports (standard UVC vs. the vendor command frame) and produce different physical zoom at the same commanded ratio, so merging them would silently change what ratio means. Pick by which behaviour you need.

AI tracking

Image & lens

Focus, white balance, and exposure each split into a dedicated _auto and _manual tool in v0.4.0 (previously one tool with a mode parameter) — auto and manual take different parameters, so splitting them lets each schema say exactly what it needs.

Capture

obsbot_capture_record and obsbot_capture_preview do not take camera. They select a device by source (device/virtual/ndi) through ffmpeg/ffplay, not by serial — there is no serial-to-ffmpeg-device mapping yet. obsbot_capture_snapshot honors camera only for source:"device"; for source:"virtual"/"ndi" the pixel source is still resolved by device name, independent of camera.

Diagnostics (--debug only)

¹ record/preview shell out to ffmpeg/ffplay (install: winget install Gyan.FFmpeg on Windows, brew install ffmpeg on macOS, apt install ffmpeg on Linux). snapshot does not need ffmpeg — it grabs the frame through the native helper.

OBSBOT Tail 2 (network cameras)

The Tail 2 is a different animal: a network PTZ camera (NDI/RTSP/SRT/RTMP output, ethernet + WiFi, and a USB-C port that is either MTP for footage offload or a UVC webcam). The tools below use its network control plane — an HTTP REST API plus a WebSocket status push, documented in TAIL2-PROTOCOL.md from on-device reverse engineering. That makes the whole module pure TypeScript with zero platform-specific code: no native helper, no helper build, identical behavior on Windows/Linux/macOS.

In UVC mode the camera also answers the standard UVC controls over USB (pan, tilt, zoom, pan/tilt speed, focus, exposure, white balance), and its vendor Extension Unit gives tracking on/off, human tracking mode, tracking speed and Auto Zoom. This server has no Tail 2 USB transport yet, so none of that is exposed as a tool; presets, portrait rotation and roll trim are network only. See TAIL2-PROTOCOL.md §11 for what was measured.

Getting started:

1. Put the Tail 2 on your network (it defaults to DHCP on ethernet).
2. Call obsbot_tail2_scan once — it listens ~5 s for the camera's own mDNS announcements (it multicasts its MAC, name and IPs every few seconds, the same channel OBSBOT Center discovers by) and falls back to an HTTP subnet sweep only on multicast-filtered networks. Or set OBSBOT_TAIL2_HOSTS (comma-separated addresses) in the server's environment, or just pass any Tail 2 tool a camera parameter holding the camera's IP.

The camera selector for these tools is the camera's MAC (its stable identity), or its device_name, or its host address — case-insensitive. Omitted with one Tail 2 registered it resolves to that one.

Every write is verified by readback (settled in the result): the Tail 2 acknowledges commands it may drop while an actuator is mid-motion — {"code":200} means acknowledged, not applied (measured 2026-09-26; see TAIL2-PROTOCOL.md §8). settled:false means the ladder ran out before the readback agreed; the command was still sent — retry it.

Known Tail 2 gaps (details in TAIL2-PROTOCOL.md §9): image-control writes via REST are unprobed, and snapshot depends on the camera's SRT output being enabled from OBSBOT Center (exclusive with NDI, cleared by reboots — the tool explains this when SRT is off; on this firmware the RTSP output never serves despite its enable flag). The camera's control API is also unauthenticated — anyone on your LAN can drive it, including poweroff.

Supported platforms

• Windows x64 — supported today. The native helper is built from source in native/windows/ (CMake + MSVC); the published npm package ships a prebuilt binary so end users need no toolchain.

• Linux x64 — supported from v0.2. The native helper is in native/linux/ (CMake + GCC); it uses V4L2 for standard UVC controls (zoom, focus, exposure, pan/tilt, white balance, image controls) and UVCIOC_CTRL_QUERY for vendor Extension Unit commands (gimbal speed/AI tracking, wake/sleep, HDR, FOV). Snapshots capture a MJPEG or YUYV frame via V4L2 mmap streaming and encode to JPEG using libjpeg. The linux-x64 prebuilt binary ships with the published npm package. Build dependencies: build-essential cmake libjpeg-dev libv4l-dev.

  Gimbal position reads (obsbot_gimbal_position) reflect the last-commanded value, not live in-flight position — see "Linux gimbal position feedback" below for why, and what would fix it.

• macOS 14+ (Apple Silicon and Intel) — supported. The native helper is in native/macos/ (Objective-C + IOKit/AVFoundation). It uses IOKit USB control transfers for both standard UVC controls and vendor Extension Unit commands, and AVFoundation for enumeration and snapshots. Both darwin-arm64 and darwin-x64 prebuilt binaries ship with the published npm package (darwin-x64 also covers Apple Silicon running Node under Rosetta, where process.arch reports x64). macOS 14 is the floor because the helper uses AVCaptureDeviceTypeExternal; the build pins -mmacosx-version-min so the binary does not inherit the build machine's OS as its minimum.

  Note on macOS specifically: UVCAssistant (a DriverKit system extension) owns the camera's UVC interfaces exclusively, so USBInterfaceOpen — and even USBInterfaceOpenSeize — fail with kIOReturnExclusiveAccess. The helper therefore opens the USB device, which is not locked, and issues UVC control requests on its default control endpoint. This coexists with UVCAssistant: the camera keeps working as a normal webcam while under control, so no driver-replacement step is needed.

Building the native helper (Linux)

cd native/linux
mkdir build && cd build
cmake ..
make -j$(nproc)
make install  # copies to native/prebuilt/linux-x64/

Linux gimbal position feedback is not live

obsbot_gimbal_position on Linux reports the last position obsbot_gimbal_move/ obsbot_gimbal_recenter commanded — not a live, in-flight reading. Hardware testing (2026-07-21) confirmed the OBSBOT Tiny 2's CT_PANTILT_ABSOLUTE control genuinely tracks live position — a raw USB read of that same control, bypassing the kernel, showed a real slew progressing in real time. The reason plain V4L2 (VIDIOC_G_CTRL) never sees that is that uvcvideo caches the control's value and serves the cache instead of re-querying the device (confirmed via VIDIOC_QUERY_EXT_CTRL, which reports no V4L2_CTRL_FLAG_VOLATILE). The driver invalidates that cache when the device sends a UVC Control Change interrupt — which this camera's firmware never does, and never advertises support for.

Getting a genuinely live reading through V4L2 requires briefly detaching the kernel driver from the camera's control interface and reading the control directly over raw USB — but detaching that interface (even briefly, even without writing anything) breaks any concurrent video capture on this device: streaming and control share one kernel-managed USB function, so pulling the driver off one takes both down together. That makes a libusb-based workaround incompatible with anything actually using the camera as a webcam at the same time, which ruled it out as a shipped default.

A kernel patch has been submitted upstream (media: uvcvideo: query pan/tilt position from the device on every read, July 2026 — awaiting review, not merged). It marks CT_PANTILT_ABSOLUTE volatile so the driver queries the device on every read; verified on this hardware to track a live slew through plain VIDIOC_G_CTRL, concurrently with streaming. If it is accepted, obsbot_gimbal_position becomes live on Linux with no code changes needed here. Until it ships in a kernel near you:

• obsbot_gimbal_move and obsbot_gimbal_recenter work normally — hardware-verified, repeatedly, via direct V4L2 VIDIOC_S_CTRL writes. Their target values are known and clamped before being sent, so they can't exceed the gimbal's mechanical range regardless of the missing feedback.
• obsbot_gimbal_move_speed is not available on Linux (hidden from the tool list entirely, not just refused at runtime). A speed×duration burst has no target position to clamp — without a live reading to confirm where the gimbal actually is, there's no way to bound it against the mechanical limits before it gets there. It remains available on Windows/macOS.

Building the native helper (macOS)

make -C native/macos    # -> native/prebuilt/darwin-arm64/obsbot-helper

Requires the Xcode command line tools. CMake works too (cmake -S native/macos -B native/macos/build && cmake --build native/macos/build), which is what CI uses.

Known limitations

What has actually been exercised against hardware, and what hasn't:

Documentation truncated — see the full README on GitHub.