Skip to main content
Glama

OBSBOT Camera MCP Server

MCP (Model Context Protocol) server for PTZ camera control with gimbal positioning, snapshots, and AI visual analysis integration.

Designed for OBSBOT Tiny SE but works with any UVC PTZ camera that supports v4l2 controls.

Features

  • Full Gimbal Control: Pan, tilt, zoom with safety limits

  • Real-time Position Feedback: Human-readable directions

  • Camera Snapshots: High-resolution capture

  • Visual Analysis: LM Studio integration for vision-language models

  • Area Scanning: Horizontal, vertical, grid, and panoramic patterns

  • Autonomous Search: Shell scripts for systematic exploration

  • Python Library: Direct control for custom applications

Related MCP server: MOSS XiaoZhi MCP

Requirements

System

  • Linux with v4l2 support

  • Node.js 18+ (for MCP server)

  • Python 3.8+ (for Python library)

Packages

# Ubuntu/Debian
sudo apt install v4l-utils ffmpeg python3-opencv

# Fedora
sudo dnf install v4l-utils ffmpeg python3-opencv

Optional

  • LM Studio for visual analysis

  • Vision-language model (e.g., Qwen2.5-VL, LLaVA)

Installation

MCP Server

cd obsbot-camera-mcp
npm install

Python Library

pip install opencv-python

Configuration

Environment Variables

export OBSBOT_DEVICE="/dev/video0"           # Camera device
export OBSBOT_OUTPUT_DIR="/tmp/obsbot"       # Capture directory
export LM_STUDIO_URL="http://localhost:1234/v1/chat/completions"
export OBSBOT_VL_MODEL="qwen2.5-vl-7b-instruct"

Claude Desktop Configuration

Add to ~/.config/claude/claude_desktop_config.json:

{
  "mcpServers": {
    "obsbot": {
      "command": "node",
      "args": ["/path/to/obsbot-camera-mcp/src/obsbot-mcp-server.mjs"],
      "env": {
        "OBSBOT_DEVICE": "/dev/video0"
      }
    }
  }
}

Usage

MCP Server Tools

get_gimbal_position

Get current pan, tilt, zoom with readable directions.

control_gimbal

Move gimbal to absolute position.

  • Pan: -468000 (right) to 468000 (left)

  • Tilt: -324000 (down) to 324000 (up)

  • Zoom: 0 (wide) to 12 (telephoto)

center_camera

Return to neutral position (0, 0, 0).

take_snapshot

Capture image with optional LM Studio analysis.

{
  "analyzeWithLM": true,
  "customPrompt": "Describe what you see"
}

look_and_analyze

Move camera and take analyzed snapshot in one operation.

scan_area

Systematic multi-position scan.

{
  "pattern": "horizontal",  // or vertical, grid, panoramic
  "steps": 5
}

check_system_status

Verify camera and LM Studio availability.

Python Library

from python.obsbot_control import OBSBOTController

camera = OBSBOTController()
camera.connect()

# Move to position
camera.set_position(pan=200000, tilt=100000, zoom=2)

# Use presets
camera.preset_position("left")
camera.preset_position("center")

# Capture
camera.save_frame("snapshot.jpg")

# Scan
results = camera.scan_horizontal(steps=5, capture=True)

camera.disconnect()

Shell Script

# Basic search
./scripts/autonomous_scan.sh "find the window"

# Grid pattern with verbose output
./scripts/autonomous_scan.sh --pattern grid --verbose "locate books"

# Quick scan
./scripts/autonomous_scan.sh --pattern quick "identify objects"

Camera Compatibility

Tested with:

  • OBSBOT Tiny SE

  • OBSBOT Meet

Should work with any UVC PTZ camera supporting:

  • pan_absolute control

  • tilt_absolute control

  • zoom_absolute control

Check your camera's controls:

v4l2-ctl -d /dev/video0 --list-ctrls

Gimbal Directions

The v4l2 control values map to directions:

  • Pan: Positive = LEFT, Negative = RIGHT

  • Tilt: Positive = UP, Negative = DOWN

  • Zoom: Higher = telephoto (zoomed in)

Troubleshooting

Camera not found

v4l2-ctl --list-devices
ls -la /dev/video*

Permission denied

sudo usermod -a -G video $USER
# Logout and login again

Controls not working

# Check available controls
v4l2-ctl -d /dev/video0 --list-ctrls

# Test manual control
v4l2-ctl -d /dev/video0 --set-ctrl=pan_absolute=100000

License

MIT License - See LICENSE file

Available Tools

7 tools
center_cameraA

Return camera to center position (pan=0, tilt=0, zoom=0)

Inputs: no named parameters.

check_system_statusB

Check camera system health and LM Studio availability

Inputs: no named parameters.

control_gimbalB

Control camera gimbal. Pan: NEGATIVE=RIGHT, POSITIVE=LEFT. Tilt: POSITIVE=UP, NEGATIVE=DOWN.

Inputs: pan, tilt, zoom.

get_gimbal_positionB

Get current camera gimbal position (pan, tilt, zoom) with human-readable directions

Inputs: no named parameters.

look_and_analyzeC

Move camera to position and take analyzed snapshot

Inputs: pan, tilt, zoom, analysisPrompt.

scan_areaC

Systematically scan area with multiple snapshots

Inputs: pattern, steps.

take_snapshotC

Capture camera snapshot with optional LM Studio visual analysis

Inputs: analyzeWithLM, customPrompt.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 7 tools

    Disambiguation4/5

    Most tools have distinct purposes, such as center_camera for resetting position, check_system_status for health checks, and control_gimbal for manual movement. However, look_and_analyze and scan_area could be confused as both involve moving the camera and taking snapshots, though scan_area implies a systematic process while look_and_analyze is more targeted.

    Naming Consistency5/5

    All tool names follow a consistent snake_case pattern with clear verb_noun structures, such as center_camera, check_system_status, and take_snapshot. The naming is predictable and readable throughout the set, with no deviations in style or convention.

    Tool Count5/5

    With 7 tools, the count is well-scoped for controlling an OBSBOT camera, covering essential operations like movement, status checks, and snapshots. Each tool appears to earn its place without being overly sparse or bloated, fitting typical server tool ranges.

    Completeness4/5

    The tool set provides good coverage for camera control, including movement (center_camera, control_gimbal, get_gimbal_position), analysis (look_and_analyze, scan_area, take_snapshot), and system checks (check_system_status). A minor gap exists in lacking explicit tools for settings management or advanced configurations, but core workflows are well-supported.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers