UVC PTZ Camera

What the UVC PTZ Camera MCP server does

The UVC PTZ Camera MCP server gives an MCP client control of a USB camera with pan, tilt, and zoom axes. It can inspect camera capabilities, point an axis at an absolute value, move relative to the reported position, run timed sweeps, set zoom, return a frame, or restore axes to their defaults.

Movement verification is based on comparing the image before and after a command. The camera's reported position is returned as device_reported, but treated as a hint rather than proof. If a requested move produces no visual change, the operation fails after a bounded retry. A request that is already at its target can succeed without moving and reports moved: false.

The server also supports named directions and views. Agents can save an orientation with aim_learn, list saved directions, navigate to one with go_to, label the current picture with mark_view, and test for changes with check_view.

How it works

plan_shot compiles a multi-step camera sequence without moving the device. It reports the steps, axis travel, and timing that run_shot would use. After planning, run_shot executes the waypoints and verifies each one. A refused device write stops the shot instead of continuing.

track_start provides a face-following loop. Each iteration detects a face, measures its distance from the frame center, applies a bounded correction, and captures another frame. track_status exposes the iteration history, including measured offsets and applied steps; track_stop ends the loop and reports its activity. Tracking can stop when the subject is lost, settles inside the dead zone, the camera stops responding, or the time limit is reached. The detector uses OpenCV's bundled face cascade and does not download a model.

Blocking camera operations, including COM calls and frame capture, run away from the event loop. Every result identifies whether the backend is simulated.

Setup and configuration

Run the package with uvx uvc-ptz-camera-mcp, or install it with pip. Windows real-camera use requires the dshow extra. uvc-ptz-mcp --list-devices shows selectable cameras, and --print-config prints a host configuration. Use --backend simulator to test without attached hardware.

The server can be added to an MCP host with a uvx command and the package name. Supply --device when more than one camera is present; the value can be a substring of the listed device name. Equivalent environment settings are UVC_PTZ_DEVICE, UVC_PTZ_BACKEND, and UVC_PTZ_STATE_DIR. Command-line flags take precedence over environment values.

The auto backend prefers a real camera and falls back to the simulator while reporting the reason. dshow selects the Windows DirectShow path, and simulator uses a camera model calibrated from the reference measurements.

Tools and capabilities

Available tools include:

• camera_status for device identity, axes, ranges, and backend state
• aim, nudge, sweep, zoom, and recentre for camera movement
• look for returning one image
• aim_learn, aim_list, and go_to for named directions
• plan_shot and run_shot for previewing and executing sequences
• mark_view and check_view for labelled picture comparisons
• track_start, track_status, and track_stop for face following

Limitations and notes

The real-device path is Windows-only. A Linux v4l2 backend is planned in the interface but is not implemented. The documented camera controls cover pan, tilt, roll, and zoom; exposure, focus, and white balance are not provided.

The reference camera's vendor extension controls cannot be reached through the Windows device path, so vendor features such as built-in subject tracking are unavailable there. The supplied follow mode is the least proven feature: its loop and arithmetic are tested against the simulator, but it has not been run against real hardware. It detects faces, not arbitrary objects, and a moving subject can appear as camera movement.

The UVC PTZ Camera MCP server uses a calibrated image-change threshold to distinguish unchanged from changed views. The calibration fixtures and measurements are kept in the repository, but no camera frames or videos are committed.