Skip to main content
Glama
lxman

obsbot-mcp

by lxman
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

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

Related MCP server: OBSBOT Camera MCP Server

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_probe tool (raw XU byte get/set/query) and the raw 60-byte status block on obsbot_get_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

Device & power

Tool

Parameters

Description

obsbot_list_devices

—

List connected OBSBOT-compatible video capture devices.

obsbot_set_run_status

state: "run" | "sleep"

Wake ("run") or sleep the camera/gimbal.

obsbot_get_status

—

Read the live status block: { awake, hdr, aiMode, trackSpeed }. Under --debug, also returns the raw 60-byte block as hex.

Gimbal (PTZ)

Tool

Parameters

Description

obsbot_ptz_move_angle

yaw, pitch, roll (degrees, roll defaults 0)

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.

obsbot_ptz_move_speed

yaw, pitch, roll (deg/s, roll defaults 0), autoStopMs (default 800)

Drive the gimbal at a speed, then auto-stop after autoStopMs so it can't run away. Same yaw/pitch sign convention as move_angle.

obsbot_gimbal_recenter

—

Recenter the gimbal (return to home position).

obsbot_gimbal_position

—

Read the gimbal's current absolute { yaw, pitch } in degrees via standard UVC Pan/Tilt. May lag a move still in progress.

Zoom

Tool

Parameters

Description

obsbot_zoom_absolute

ratio (1.0–2.0)

Set absolute zoom ratio, clamped to [1.0, 2.0].

obsbot_zoom_speed

ratio (1.0–2.0), speed (default 0)

Zoom to a ratio at a chosen speed: 0 = device default, 1–10 slow→fast, 255 = maximum.

AI tracking

Tool

Parameters

Description

obsbot_ai_tracking

enabled (bool), mode (default "normal")

Enable/disable AI subject tracking and choose framing: normal | upper-body | close-up | headless | lower-body. Polls status and returns { verified, matched } (matched:false = no subject tracked yet).

obsbot_ai_track_speed

speed: "standard" | "sport"

Set the tracking-speed preset (Center's Standard/Sport): standard (slower follow) or sport (snappier).

obsbot_face_focus

enabled (bool)

Enable or disable face-priority autofocus.

Image & lens

Tool

Parameters

Description

obsbot_fov

fov: "wide" | "medium" | "narrow"

Set the field of view: wide (86°), medium (78°), narrow (65°).

obsbot_hdr

enabled (bool)

Toggle HDR/WDR imaging on or off.

obsbot_focus

mode: "auto" | "manual", position (0–100, default 50)

auto = continuous autofocus; manual = set the focus motor to position (near→far).

obsbot_exposure

mode: "auto" | "manual", level (0–100, default 50)

auto = auto-exposure; manual = set level (0 darkest → 100 brightest).

obsbot_white_balance

mode: "auto" | "manual", temperature (Kelvin, default 5000)

auto = auto white balance; manual = set a colour temperature (clamped to device range).

obsbot_image_control

control, level (0–100)

Adjust brightness | contrast | hue | saturation | sharpness | gain | backlight-compensation; level maps onto the device range.

Capture

Tool

Parameters

Description

obsbot_snapshot

maxDim (256–1920, default 1024), quality (1–100, default 80), settleMs (default 600), source (default "device")

Grab one still frame and return it as an image (for framing/lighting/exposure checks). source: device | virtual | ndi.

obsbot_record_start

durationSec (optional), audio (default true), outputPath (optional), source (default "device")

Start recording to MP4. Open-ended recordings auto-stop after 60 min; audio uses the OBSBOT mic; defaults under Videos/OBSBOT. Returns a sessionId. **Needs ffmpeg.**¹

obsbot_preview_start

source (default "device")

Open a live preview window. Returns a sessionId. **Needs ffplay.**¹

obsbot_capture_stop

sessionId

Stop a recording or preview session (recordings are finalized gracefully).

obsbot_capture_list

—

List active recording/preview sessions.

Diagnostics (--debug only)

Tool

Parameters

Description

obsbot_probe

mode: "get" | "set" | "query", plus selector, length, hex, opcode, payloadHex

RE/diagnostics only — raw XU byte get/set and framed table queries. Advertised only under --debug.

¹ 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.

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 / macOS — not yet implemented. The design is platform-agnostic (see PROTOCOL.md); adding support means writing an equivalent native helper for each OS's UVC control APIs (V4L2 on Linux, AVFoundation/IOKit on macOS) behind the same JSON-RPC-over-stdio contract used by the Windows helper. Contributions welcome.

No proprietary SDK

This project speaks the camera's USB protocol directly through the OS's standard UVC driver stack and does not use, link, bundle, or ship any vendor SDK. See PROTOCOL.md for the protocol reference (frame format, checksum, command table).

How it works

The camera exposes two independent control surfaces, both reachable through the OS's standard UVC (USB Video Class) driver stack — this project never talks to the USB device directly, so the OS keeps mediating access and the camera remains usable as a normal webcam at the same time commands are sent:

  • Standard UVC controls — zoom (CT_ZOOM_ABSOLUTE), focus and exposure (IAMCameraControl), gimbal position readback (UVC Pan/Tilt), and the image controls plus white balance (IAMVideoProcAmp) — are the camera's built-in UVC properties, driven via DirectShow on Windows.

  • Vendor commands — gimbal moves, recenter, wake/sleep, AI tracking, HDR, and field of view — are sent through the camera's UVC Extension Unit, driven via IKsControl::KsProperty against the XU's topology node on Windows.

Both are issued through a small native helper process (obsbot-helper.exe on Windows) that the Node server spawns and talks to over a line-delimited JSON-RPC protocol on stdin/stdout. The helper is the only platform-specific piece; the codec (frame encoding, CRC-16/USB checksum, command table), transport abstraction, device manager, and MCP tool definitions are all pure TypeScript/JavaScript and shared across platforms.

Verifying against real hardware

scripts/e2e.mjs drives the built stack (dist/) against a physically connected camera: it wakes the device, zooms in, pans the gimbal, recenters, zooms back out, and puts the camera to sleep, with a short pause and console log before each step so a human can watch it happen. This moves the physical gimbal — only run it under supervision:

npm run build
node scripts/e2e.mjs

This server cannot be installed

A
license - permissive license
-
quality - not tested
A
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
1Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/lxman/obsbot-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server