# UVC PTZ Camera [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/AbhijatSaxena/uvc-ptz-camera-mcp  
**GitHub Stars:** 0  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/uvc-ptz-camera

## Description
Control a USB (UVC) pan/tilt/zoom camera, with every move confirmed from the picture.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "uvc-ptz-camera": {
    "command": "uvx",
    "args": ["uvc-ptz-camera-mcp"],
    "env": {
      "UVC_PTZ_DEVICE": "",
      "UVC_PTZ_BACKEND": "",
      "UVC_PTZ_STATE_DIR": ""
    }
  }
}
```

**Requires environment variables:** `UVC_PTZ_DEVICE`, `UVC_PTZ_BACKEND`, `UVC_PTZ_STATE_DIR` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

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

_Full upstream README: https://allmcps.com/mcp/uvc-ptz-camera/readme_