MCP 服务器

onvif-mcp

MCP server that lets AI agents interact with IP cameras via ONVIF/VAPIX, with fail-closed per-agent policy gates and hash-chained signed audit receipts.

README

onvif-mcp

The governed doorway between AI agents and video infrastructure.

Every tool call passes a fail-closed policy gate and emits a hash-chained, signed receipt — including denials.<br> The audit trail records what agents tried, not just what they did.

<a href="https://github.com/oneshot2001/aar">AAR specification</a> · <a href="docs/aar-alignment.md">Conformance plan</a> · <a href="#quick-start">Quick start</a> · <a href="https://github.com/oneshot2001/onvif-mcp/issues">Report an issue</a>

</div>

Agents are getting wired into everything. Nobody has shipped agent access to cameras and video systems that a security director could approve. This is that attempt.

Features

Four MCP tools over stdio: list_cameras, get_snapshot, ptz_move, get_receipts
Fail-closed per-agent policy — tool allowlist, camera allowlist, PTZ step bounds per agent identity; unknown agents get nothing
Signed receipts on every call — hash-chained JSONL, ed25519-signed, produced frames content-hashed into the receipt; one altered byte is detected at the exact sequence number
Dual transport — AXIS VAPIX and ONVIF SOAP behind one tool contract, selected per camera
No secrets on disk — camera credentials resolve from a local credential store at startup and are never written or logged

Quick start

bun install

Describe your cameras in cameras.json:

{
  "lobby": { "base": "http://192.168.1.33", "user": "root", "credKey": "cam-lobby",
             "ptz": true, "protocol": "vapix" },
  "gate":  { "base": "http://192.168.1.32", "user": "root", "credKey": "cam-gate",
             "ptz": true, "protocol": "onvif", "profile": "profile_1_jpeg" }
}

Grant agents authority in policy.json (anything not granted is denied):

{
  "agents": {
    "claude-main": {
      "tools": ["list_cameras", "get_snapshot", "ptz_move", "get_receipts"],
      "cameras": ["lobby", "gate"],
      "ptz": { "maxStep": 30 }
    }
  }
}

claude mcp add cameras -- env AGENT_ID=claude-main bun /path/to/onvif-mcp/index.ts

Audit the receipt chain any time:

bun index.ts --verify
# chain OK — every hash linked + signature valid

Tools

Tool	Does	Policy checks
`list_cameras`	Live device info for cameras this agent may see	agent known, tool granted
`get_snapshot`	Capture a JPEG, return path + SHA-256	+ camera granted
`ptz_move`	Relative pan/tilt/zoom in degrees	+ camera granted, camera is PTZ, step within `maxStep`
`get_receipts`	Tail the signed receipt chain	agent known, tool granted

Every call — allowed or denied — appends a receipt. A denial looks like this:

{ "seq": 19, "profile": "aar-0.2-draft-alignment",
  "principal": { "role": "agent", "type": "service", "id": "claude-main" },
  "enforcement_point": "onvif-mcp/0.1.0", "node_kind": "authorization",
  "action": { "tool": "ptz_move", "params": { "camera": "gate", "pan": 90 } },
  "decision": "deny", "detail": "step exceeds policy maxStep 30°",
  "prev": "8fb7…", "hash": "8322…", "sig": "jRld…" }

Receipts and the AAR spec

Receipt semantics follow the Agent Action Receipts (AAR) v0.2 vocabulary: principals, enforcement points, node kinds (observation, action_attempt, authorization), and calibrated outcome-evidence levels (device_acknowledged, independently_sensed, unknown).

Honesty note: wire conformance to AAR v0.2 (deterministic CBOR, detached COSE_Sign1 ES256) is not claimed yet. The current chain is a draft transport. The gap analysis and conformance plan live in docs/aar-alignment.md.

Transports

Set protocol per camera: "vapix" (AXIS HTTP CGI) or "onvif" (SOAP services). Verified live against AXIS hardware: on AXIS OS 12.9.57 the admin user works for ONVIF over HTTP digest; older 12.x firmware requires a separate ONVIF account provisioned in the web UI. ONVIF RelativeMove uses the generic translation space — pan converts as degrees/360 (measured exact on hardware); tilt/zoom mapping is linear-approximate.

Status

Experimental (v0.1.0). Verified live against three AXIS cameras (two PTZ, one fixed dome) through real MCP client round-trips: physical PTZ motion with before/after frame proof, all denial paths exercised and receipted, and tamper-detection confirmed by mutating a receipt and watching --verify flag the exact sequence. Not production software — see the roadmap.

Roadmap

AAR v0.2 wire-conformant receipt producer (CBOR + COSE, verified against the spec's byte-pinned KATs)
Per-agent signing keys and signed policy objects (agent commissioning)
Clip/recording export
Non-AXIS ONVIF hardware validation

Trademark note

ONVIF® is a trademark of ONVIF, Inc. This project is not affiliated with, endorsed by, or certified by ONVIF, Inc. The name is purely descriptive — this server speaks the ONVIF protocol as published in the open specifications. No ONVIF conformance is claimed or implied. No ONVIF logos are used and no WSDL files are redistributed; the SOAP envelopes are hand-authored.