lxman/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
MCP client configuration
Add a stdio server entry pointing at the installed binary (or directly at dist/index.js):
If you're running from a local checkout instead of an npm install, point command/args at
node and the built entry point instead:
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:
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 32 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
| Tool | Parameters | Description |
|------|------------|-------------|
| obsbot_devices | — | List attached OBSBOT cameras with each one's serial (where obtainable), name, and status (available/bound/busy). A busy camera is held by another process. |
| obsbot_wake | camera? | Wake the camera/gimbal (sends "run"). **Moves the camera:** un-stows the gimbal back to level (pitch ~0). Most control commands also wake it implicitly. |
| obsbot_sleep | camera? | Sleep the camera/gimbal (sends "sleep"). **Moves the camera:** stows the gimbal face-down at roughly pitch 84, so obsbot_gimbal_position reads ~84 rather than the pose you left. |
| obsbot_status | camera? | Read the live status block: { awake, hdr, faceAe, aiMode, trackSpeed, fovMode, zoomPercent, focusMode, focusPosition } (faceAe = auto-exposure metering for a detected face; fovMode = wide\|medium\|narrow\|custom\|unknown, where custom means a continuous zoom overrode the discrete modes; zoomPercent = zoom position, 0-100; focusMode = auto\|manual\|unknown). **focusPosition appears only in manual mode**, on the same 0-100 scale obsbot_focus_manual takes — under autofocus the camera echoes the last written value rather than exposing the motor, so a number there would read as a live focus distance while being stale. Focus is a standard UVC control, not part of the status block, so it costs one extra read; a device that can't answer reports focusMode: "unknown" rather than failing the whole call. Under --debug, also returns the raw 60-byte block as hex. |
Gimbal (PTZ)
| Tool | Parameters | Description |
|------|------------|-------------|
| obsbot_gimbal_move | yaw, pitch, roll (degrees, roll defaults 0), camera? | Move the gimbal to an absolute angle. Positive yaw pans to the camera's left, positive pitch tilts down. Yaw clamped to [-150, 150], pitch to [-90, 90]. Absolute 1:1 degrees, hardware-verified. |