uvc-ptz-camera-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@uvc-ptz-camera-mcp pan the camera to 180 and confirm it moved"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
uvc-ptz-camera-mcp
An MCP server for USB (UVC) pan/tilt/zoom cameras: aim them, nudge them, sweep them smoothly, zoom, and look through them — with every move confirmed by comparing the picture before and after.
No account, no cloud, no vendor SDK. One device, one USB cable.
camera_status the camera, its axes and ranges, and whether it is real
aim point an axis at an absolute value, confirmed from the picture
nudge move relative to where the device says it is
sweep a smooth timed move, streamed at 15 Hz
zoom set zoom as a multiplier (1x .. the camera's maximum)
recentre every axis back to its default
look one frame, returned as an image
aim_learn remember "this direction is the desk"
aim_list what has been recorded for this camera
go_to point at a recorded direction
plan_shot compile a multi-step shot and report what it would do, moving nothing
run_shot execute a multi-step move, verified after every waypoint
mark_view store the current picture under a label
check_view has the picture changed since that label?
track_start follow a subject: detect, measure, take a step, look again
track_status what the follow loop is doing, iteration by iteration
track_stop stop following and report what it saw and what it movedComposing a shot is plan_shot then run_shot. Planning compiles exactly the steps the executor
will compile, reports the per-step schedule, how far each axis travels and how long it takes, and
touches nothing — so an agent can iterate on "a panorama, then zoom in on me" against the camera's
real ranges before anything moves, instead of finding out afterwards.
Following
track_start runs a loop that keeps the camera pointed at a subject: detect it, measure how far it
is from the centre of the frame, take a bounded step, look again. It decides only from the picture,
for the same reason every other move here does — this camera's own report of where it is pointing
cannot be trusted. It stops on its own when the subject is lost, when it settles inside the dead
zone, when the camera stops answering, or after max_seconds, and track_status lists every
iteration with the offset it measured and the step it applied.
Two quantities are mount-dependent rather than device-dependent, so they are explicit parameters
instead of clever guesses: gain, degrees of movement per pixel of offset, and invert, which
flips the direction. A wrong choice shows up honestly as a residual error that grows, and a single
iteration is capped at 25 degrees, so a wrong gain converges slowly rather than throwing the camera
across its whole range in one command.
Detection uses OpenCV's bundled face cascade (pip install 'uvc-ptz-camera-mcp[tracking]'), which
needs no model download, no account and no network at first use. It finds faces: this follows a
person, not a car or a dog. The loop and its arithmetic are tested against the simulator, but no
part of follow mode has ever run against real hardware — treat it as the least proven thing here.
Why this exists
This class of camera reports positions it never moved to. Measured on the reference device (a DJI Osmo Pocket 4P in webcam mode, over its standard UVC controls):
a command to pan to
180read back180while the video proved the camera had not moved at all;a whole 32-second run read back
0on every sample while the frame demonstrably changed;pan
120read back119, pan200read back199.
An agent acting on those values reports moves that never happened. So this server treats every
device-reported value as a hint — returned, labelled, never trusted — and decides moved
by comparing frames.
The threshold is not a guess either. It was calibrated on labelled hardware frames: every
"same view" pair scored ≤ 0.104 (a 96-second quiet baseline, and two commands the hardware
ignored), every "view changed" pair scored ≥ 0.624 (a pan, a tilt, a 12× zoom, two aim
steps). The shipped threshold is the midpoint, 0.364 — a 6× separation — and the test suite
asserts it still separates them. The labelled pairs and the values the metric produced are kept in
the repository (tests/fixtures/) so the number can be re-checked rather than
believed — as measurements, not pictures: no frame or video taken by a camera is committed here,
and a test fails if one appears. The measurements behind the calibration are in
docs/measurements.md.
Related MCP server: obsbot-mcp
What keeps the agent honest
movedcomes from the picture.device_reportedis returned beside it, labelled a hint.A move that produced no change is an error, not a quiet success — after a bounded retry, the tool fails naming what was requested and what was observed.
Already being at the target is success without movement:
moved: false, no error.Blocking work never runs on the event loop (COM calls, ffmpeg captures), pinned by a test that records which thread the camera was touched on.
Observation is explicit: nothing takes a picture except a tool you called.
A refused write aborts a shot rather than continuing to drive a camera that stopped listening.
Install
uvx uvc-ptz-camera-mcp # run without installing
pip install uvc-ptz-camera-mcp # or install itFor a real camera on Windows you also need the DirectShow extras:
pip install "uvc-ptz-camera-mcp[dshow]"Then point your host at it — --print-config emits the snippet with the right interpreter:
uvc-ptz-mcp --print-config
uvc-ptz-mcp --list-devices # what to pass to --device
uvc-ptz-mcp --backend simulator # try it with no camera attachedWhere to put it
Claude Desktop, Cursor, VS Code and friends all take the same shape — this is the whole configuration, because there is nothing to authenticate:
{
"mcpServers": {
"ptz-camera": {
"command": "uvx",
"args": ["uvc-ptz-camera-mcp"]
}
}
}Add "--device", "Osmo" (any substring of the name --list-devices prints) when the machine has
more than one camera, and "--backend", "simulator" to work with none. Both can also be set in the
environment instead of the args — UVC_PTZ_DEVICE, UVC_PTZ_BACKEND and UVC_PTZ_STATE_DIR — which
is what the Claude Desktop bundle uses, and which survives a host restart without editing its config
again. A flag wins over the environment, and an empty value means "not set" (a host that leaves an
option blank writes "", not nothing). Claude Desktop also accepts the .mcpb bundle attached to
each release as a one-click install.
Modes, and how you can tell which one you are in
Backend | What it is |
| Prefer a real camera; fall back to the simulator, saying why |
| Windows DirectShow: the real device path |
| No hardware at all: a model calibrated from the measurements below |
Every result carries "simulated": true or false, and camera_status reports the reason when
the simulator is standing in. Nothing quietly pretends to be hardware: a caller must never
believe it is driving a camera when it is driving a model.
The simulator is calibrated from the reference device, not invented: ~0.4 s from write to first motion, a pan completing in about a second, a 4× zoom in about 2.5 s, silently dropped writes, and a read-back that echoes a request the hardware never applied. It renders frames by cropping a wide panorama, so a simulated pan genuinely changes the pixels — a simulator with a static picture would let verification pass vacuously.
Honest limitations
The real-device path is Windows-only (DirectShow). A Linux backend would use
v4l2; the interface is in place, the implementation is not written.No exposure, focus or white balance. The reference camera exposes no Processing Unit at all — only pan/tilt/roll/zoom.
The vendor Extension Unit is unreachable on Windows, so features that live there (on the reference camera, its built-in subject tracking) cannot be driven from software. Measured:
IKsControlis refused on the device filter,IKsTopologyInfolists three nodes and no vendor node, andCreateNodeInstancefails on all of them. Linux can reach it throughuvcvideo'sUVCIOC_CTRL_QUERY; that is a separate backend.A moving subject looks like a moving camera. Frame comparison cannot tell the two apart; the metric is calibrated so that a static scene behaves, and
check_viewis there for judging a view rather than a move.One unusable device must not hide the others. A registered-but-unavailable virtual camera raised when its DirectShow moniker was bound, which aborted a listing that should have returned two working cameras. Enumeration now skips what it cannot load and says so, and the same rule applies inside the backend when it looks for the camera you named.
Measured latency sets the ceiling: ~0.4 s from command to motion, so control loops run at a couple of hertz, not tens. That is the hardware's floor, not the software's.
The DirectShow path is tested but dormant. The reference device was returned partway through development, so the hardware path is exercised up to its interface and typed correctly against it, while the simulator carries the test load. Treat the first run against a real camera as the true acceptance test.
Development
pip install -e ".[dshow]" numpy pytest pytest-asyncio ruff
python -m pytest -q # 39 tests, three layers
python -m ruff check . && python -m ruff format --check .The suite is layered deliberately: the tool surface in-process against the simulator (mapping, validation, honest failure), pure unit tests for the compiler and the metric, and a real stdio handshake as a subprocess — including one run with a device name that cannot exist, because a server that dies at startup is invisible to every host and directory that lists it.
Reference device
Built against a DJI Osmo Pocket 4P in webcam mode: VID_2CA3 / PID_0023, exposing pan
−38…215°, tilt −33…105°, roll ±35°, zoom 100…1200 (1×–12×) as standard UVC camera controls.
Any UVC PTZ camera exposes the same surface; the ranges are read from the device at startup
rather than assumed, and nothing vendor-specific is hard-coded.
Not affiliated with, endorsed by, or supported by DJI.
Available Tools
17 toolsaimA
Point one axis at an absolute value, and return what the picture confirms.
axis is one of pan, tilt, roll, zoom. Gimbal axes are in degrees; zoom is the device's
own ratio x100, so 300 means 3x. The value is clamped to the range the camera advertises
and the clamped value is what gets sent.
This moves the camera and waits for it: allow roughly a second for a gimbal axis and
three for a zoom. moved is decided by comparing frames, never by the device's report --
the report is returned as device_reported and labelled a hint, because this hardware
was measured claiming positions it had not reached. If the picture shows no change and
the camera was not already at the target, the call fails rather than reporting success.
Inputs: to (required), axis (required).
aim_learnA
Remember the current direction under a name, for later use.
Pan is an absolute axis whose meaning depends on where the camera is standing, so
"point at the door" is unanswerable without recording it once. Call this with the camera
already pointed where you want, and the label becomes usable with go_to.
Inputs: label (required).
aim_listA
List the directions recorded for this camera, and its calibrated default pose.
Inputs: no named parameters.
camera_statusA
Report the camera, its axes and ranges, and whether it is a real device.
Call this first. It says which camera was found, the range each axis accepts, where the
camera believes it is pointing (a hint, not proof), what has been calibrated, and -- if
no real device was found -- the reason. simulated: true in any result means nothing
physical moved and no picture was ever taken.
Inputs: no named parameters.
check_viewA
Compare the current picture with one stored by mark_view.
Answers "is the camera still looking at what it was looking at?", which is the question a scene change can otherwise hide: a person walking through the shot changes the picture as much as a pan does, so treat a small difference as "still there" and a large one as "worth looking at".
Inputs: label (required).
go_toA
Point the camera at a direction recorded earlier with aim_learn.
Each axis is moved and confirmed from the picture, the same as aim. A label is resolved
to the angles recorded for it, which may drift if the camera has been physically moved
since; the picture check still proves that each axis moved, not that the label is right.
Inputs: label (required).
lookA
Capture one frame of what the camera currently sees, as a PNG image.
This observes the camera's view. Call it when the user asks to see the picture, not on your own initiative, and be aware that a still only tells you what is in front of the lens -- not where the camera is, and not whether a move happened.
Inputs: no named parameters.
mark_viewA
Store the current picture under a label, so it can be compared later.
Useful before a move whose result you will judge later, or to establish what "the wide shot" looks like. Marks live in memory for this session only.
Inputs: label (required).
nudgeB
Move one axis relative to where the device says it is now.
Relative moves inherit the device's reported position, which is a hint: after a series of nudges the accumulated position may drift from belief. The picture check still tells you whether this call moved the camera; it cannot tell you it is at an absolute angle.
Inputs: by (required), axis (required).
plan_shotA
Compile a shot and report what it would do, without moving the camera.
Takes exactly the step list run_shot takes: each step is an object like
{"axis": "pan", "to": 60, "seconds": 2.5, "ease": "in_out"}, optionally with
{"hold": 1.0} to pause after it. Every step is validated against the camera's advertised
ranges and clamped exactly as it would be at execution time, so an impossible or
out-of-range shot is refused here, before anything moves.
Use this to compose a shot. It returns the per-step schedule (where each axis starts, the value it was clamped to, how far it travels, how many ticks it costs), the per-axis envelope, the total duration, and the axes with their ranges so the next attempt can be written against the real limits. Nothing is written to the camera and no frame is captured, so it is safe to call as often as you like while deciding.
The from values come from the device's own position report, which this server treats as a
hint rather than a fact. run_shot recompiles from the same hint when it runs, so a plan
and its execution agree unless the camera moved in between.
Inputs: steps (required).
recentreA
Return every axis to the camera's own default: centre, level, unzoomed.
Inputs: no named parameters.
run_shotA
Execute a multi-step camera move, verifying after every waypoint.
Each step is an object: {"axis": "pan", "to": 60, "seconds": 2.5, "ease": "in_out"}. Steps run in sequence and every axis that moves in a step is written on each tick, so a step naming two axes produces a genuine diagonal rather than a staircase. Add {"hold": 1.0} to pause after a step.
The whole plan is validated against the camera's advertised ranges before anything moves, so an impossible shot fails without touching the hardware. Afterwards the report gives the picture difference at each waypoint, which is how you tell a shot that happened from one that did not. A long shot takes its full duration; do not set a host timeout shorter.
Inputs: steps (required).
sweepA
Move an axis smoothly to a value over a chosen duration.
Use this for any move that should read as deliberate: a slow pan across a scene, a
gradual push in. The axis is driven by streaming absolute targets at 15 Hz rather than
one jump, which is how this hardware was measured moving smoothly. ease is one of
linear, in_out, out, in; in_out starts and stops gently, which is what makes a move look
intentional. Long sweeps take as long as seconds, so expect to wait.
Inputs: to (required), axis (required), ease, seconds.
track_startA
Start following a subject, closing the loop on the picture.
While this runs the server keeps capturing frames and moving the camera to hold the subject near the centre of the frame: detect, measure the offset, take a bounded step, look again. It decides only from the picture, because this class of camera's position report cannot be trusted -- and it reports the residual offset every iteration, so a loop that is losing the subject looks like one instead of seeming to work.
It looks at whatever the camera sees for as long as it runs, which may be a room with people
in it. Start it when the user wants the camera following something, and stop it when they do
not. It also stops by itself: when the subject is lost for a while, when it settles inside
the dead zone, or after max_seconds.
gain is degrees of camera movement per pixel of offset -- a starting point, not a
measurement. invert flips the direction, which is what a differently mounted camera needs:
if the camera drives away from the subject, the sign is wrong for this mount, so read
track_status and start again with invert true. Movement is capped at 25 degrees per
iteration, so a badly wrong gain converges slowly rather than throwing the camera across
its range.
Inputs: gain, invert, target, max_seconds, +1 more.
track_statusA
Report what the follow loop is doing, with the evidence for each iteration.
Every iteration appears with the measured offset and the step applied, so a loop that is
driving the wrong way shows up as a residual distance that grows, and one whose moves the
picture never confirms shows up in move_failures rather than as apparent success.
Inputs: no named parameters.
track_stopA
Stop following, and return the summary: what it saw, what it moved, what failed.
Inputs: no named parameters.
zoomA
Set optical zoom as a multiplier: 1.0 is wide, up to the camera's maximum.
Convenience over the raw zoom axis, which counts in hundredths. The requested ratio is clamped to what the camera supports and the clamped value is returned.
Inputs: ratio (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 17 tools
Most tools have distinct roles, but several movement tools overlap in surface: aim, nudge, sweep, go_to, zoom, and run_shot all move axes, and an agent must read descriptions closely to pick the right one. The descriptions do differentiate them effectively (absolute vs relative vs smooth-timed vs labeled-direction vs multi-step), and pairs like plan_shot/run_shot and mark_view/check_view are clearly complementary.
Names are consistently snake_case, with single verbs (aim, nudge, sweep, zoom, look) for atomic actions and verb_noun compounds (run_shot, track_start, mark_view, check_view, aim_learn) for compound operations. Minor deviations like camera_status (noun_noun) and go_to (verb_prep) break the verb pattern slightly but remain readable and predictable.
17 tools is slightly heavy but each earns a place: movement (aim, nudge, sweep, zoom, recentre, run_shot, plan_shot, go_to), tracking (track_start/status/stop), observation (look, mark_view, check_view), and calibration/presets (camera_status, aim_learn, aim_list). The one genuine redundancy is the plan/execute split, which still adds validation value.
The surface covers the full PTZ lifecycle: status/ranges, single- and multi-axis movement, smooth sweeps, tracking with evidence, named presets, image capture and comparison. The main gap is no explicit abort/cancel for an in-flight run_shot or sweep (only track_stop exists for the follow loop), which agents must work around with timeouts.
Maintenance
Related MCP Connectors
Turns a phone into a camera+Bluetooth remote so AI assistants can see and control any PC.
Give the physical world an API: cameras become typed endpoints your agent can read and act on.
Ask your security cameras anything and set up alert rules in a sentence. Built into Agent DVR.
Eyes and hands on real Windows PCs — observe, click, type via Glasswarp API.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables PTZ camera control with gimbal positioning, snapshots, and AI visual analysis for OBSBOT and UVC cameras. Supports autonomous scanning patterns and integrates with vision-language models for real-time camera analysis.71MIT
- AlicenseBqualityBmaintenanceControls an OBSBOT Tiny 2 camera gimbal, zoom, and wake/sleep over UVC/USB without any vendor SDK.82400 npm5MIT
- AlicenseNot gradedqualityDmaintenanceEnables capturing live images from a USB camera and checking camera health via natural language.MIT
- AlicenseNot gradedqualityDmaintenanceEnables control of OBSBOT Tiny-series cameras (gimbal, zoom, focus, AI tracking, snapshots) through MCP tools.1MIT