obsbotd

A Linux MCP daemon for OBSBOT Tiny-series cameras. One daemon owns the camera; every agent — Claude Code, LibreChat, custom frameworks, or anything that can POST JSON — connects to it over streamable-http.

MCP clients (any framework, or bare curl)
        │  streamable-http  http://127.0.0.1:8626/mcp
        ▼
     obsbotd  ──►  V4L2/UVC ioctls (ctypes)   gimbal, zoom, focus, status
              ──►  vendor XU protocol         wake/sleep, AI tracking, exposure
              ──►  ffmpeg                     snapshots (validated), clips, preview

Why this exists

The upstream obsbot-mcp npm package did the hard part — reverse-engineering the vendor protocol and calibrating the optics — but its architecture (a stdio MCP server per agent session, a prebuilt native helper binary, single-owner IPC election between sessions) produced chronic operational pain on a multi-agent Linux machine: stale owner processes serving weeks-old code, unvalidated truncated frames, and a closed binary the bugs lived in.

obsbotd keeps the protocol knowledge and throws away the architecture:

• One daemon, many clients. No elections, no per-session processes, no stale owners. Runs as a systemd user service.

• No native binary. The V4L2/UVC layer is ~200 lines of ctypes; ioctl numbers are computed from struct sizes so a layout mistake fails loudly.

• Hotplug is free. No device handle is held between calls — every tool call re-discovers /dev/video* (sub-millisecond). Unplugging the camera yields {"ok": false, "camera_present": false} as a normal result; the next call after a replug just works.

• Frames are validated. The camera sporadically emits truncated MJPEG frames, worst right after wake. Every snapshot is a stream-copied raw frame checked for a complete SOI..EOI, retried up to 4x, then optionally downscaled (default 640 px — snapshot pixels are LLM tokens).

• Honest errors. Every failure is a structured {ok: false, error} an agent can act on — never an opaque tool exception. Refusal messages say what to do instead.

• Atomic pan+tilt. Both axes in one VIDIOC_S_EXT_CTRLS — uvcvideo's per-control read-modify-write otherwise cancels half the move.

• Measured optics. obsbot_aim_at_pixel / obsbot_zoom_to_fit do visual servoing with the intrinsics-solved FOV model (67° wide HFOV, 0.957 vertical correction, magnification = 3·ratio − 2) and composed-rotation aiming inherited from upstream's calibration work.

Hardware support

Developed and hardware-verified against an OBSBOT Tiny 2 Lite on Linux (kernel uvcvideo). The Tiny 2 shares the vendor protocol and should work unchanged; other OBSBOT models are untested. Single camera per host.

Known kernel limitation: uvcvideo caches CT_PANTILT_ABSOLUTE, so gimbal readback is the last-commanded pose, not live — the tools are labeled accordingly, and the intended workflow verifies pointing visually.

Install

Requires Python ≥ 3.12, ffmpeg (and ffplay for the preview window), and read/write access to the camera's /dev/video* node (the video group).

git clone https://github.com/LumenPrima/obsbotd ~/obsbotd
cd ~/obsbotd
uv venv && uv pip install -e .        # or: python3 -m venv .venv && .venv/bin/pip install -e .
.venv/bin/python -m obsbotd.server    # listens on 127.0.0.1:8626

As a service:

cp systemd/obsbotd.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now obsbotd
loginctl enable-linger $USER          # optional: run without an active login

OBSBOTD_HOST / OBSBOTD_PORT override the bind address. The default is localhost-only and there is no authentication — do not bind it to a reachable interface unless you understand that anyone who can reach the port can drive the camera and take pictures.

Connect an agent

MCP-native config (Claude Code, most frameworks):

{ "mcpServers": { "obsbot": { "type": "http", "url": "http://127.0.0.1:8626/mcp" } } }

No MCP library? The server answers bare JSON-RPC POSTs with plain JSON — a naive agent can drive it with curl. docs/AGENT-GUIDE.md has the full integration guide, the 18-tool reference, and the rules of engagement (no sleeps, verify motion visually, treat refusals as instructions).

Tools (18)

obsbot_snapshot · obsbot_status · obsbot_wake · obsbot_sleep · obsbot_gimbal_move · obsbot_gimbal_recenter · obsbot_gimbal_position · obsbot_zoom · obsbot_aim_at_pixel · obsbot_zoom_to_fit · obsbot_ai_track · obsbot_ai_track_speed · obsbot_focus · obsbot_exposure · obsbot_image_adjust · obsbot_image_mode · obsbot_record_clip · obsbot_preview

Protocol documentation

docs/spec-*.md is a complete written specification of the vendor wire protocol (60-byte V3 frames, CRC-16/USB, opcode tables, the 60-byte status block, selector map) and the measured optics — extracted from upstream's source as the reimplementation reference, and useful on its own to anyone driving these cameras. The wire layer is golden-tested against upstream's exact frame bytes (tests/).

Tests

tests/ are hardware-free: .venv/bin/python -m pytest tests/ -q

Credits

The vendor protocol reverse engineering, hardware quirk catalog, and optical calibration all come from obsbot-mcp (MIT, © 2026 Michael Jordan). obsbotd is an independent Linux-native reimplementation of the serving architecture around that knowledge.

License

MIT — see LICENSE.