hikvision-mcp

A local, capability-aware MCP server for safely inspecting and configuring Hikvision cameras. The current release implements the PRD's first end-to-end vertical slice:

• TOML configuration and environment-variable secrets;

• per-camera and per-tool permission enforcement;

• async ISAPI with digest authentication, safe XML parsing, and bounded event streaming;

• camera identity and capability probing;

• warning-light read and partial configuration updates using the camera's JSON schema;

• read-only intrusion regions, targets, arming schedules, and event linkage;

• read-only motion, tamper, line-crossing, intrusion, region entrance/exit, and scene-change rules with zones, schedules, targets, and linkage;

• camera health, stream profiles, image/day-night settings, storage status, audible-alarm configuration, and two-way-audio capability reads;

• bounded live alert monitoring with semantic event type and active/inactive state;

• mandatory proposal/apply approval fallback;

• conflict detection, verified read-back, SQLite audit/change history, and rollback;

• stdio and localhost Streamable HTTP MCP transports.

The warning-light, field-detection, and alert-stream adapters have sanitized fixture coverage for DS-2CD2346G2-ISU/SL firmware V5.7.14 and V5.7.19. The expanded read surface has sanitized V5.7.19 fixture coverage. Hardware writes still require explicit approval and should be opt-in until a PUT/read-back cycle has been validated on the target. Firmware differences belong in adapter subclasses, never MCP handlers.

Compatibility

The reference hardware is a DS-2CD2346G2-ISU/SL. Other Hikvision devices are handled through capability probing, automatic or configured channel selection, and model/firmware adapter registration; they are not claimed as tested until sanitized fixtures or hardware evidence are added.

Install

uv sync --extra dev
Copy-Item config.example.toml config.toml
$env:HIKVISION_CAMERA_USERNAME = "service-account"
$env:HIKVISION_CAMERA_PASSWORD = "..."

On Linux or macOS, use cp and export for the equivalent file copy and environment values.

Keep config.toml local and never commit credentials. Validate and run:

uv run hikvision-mcp config validate --config config.toml
uv run hikvision-mcp serve --transport stdio --config config.toml
uv run hikvision-mcp serve --transport streamable-http --config config.toml

The HTTP MCP endpoint is http://127.0.0.1:8000/mcp by default.

Safe mutation flow

The example configuration is read-only. Deliberately raise both the server and camera policy ceilings to Level 3 before using this flow.

1. Call get_capabilities(camera="example_camera").

2. Call get_warning_light.

3. Call configure_warning_light; this only creates a proposal.

4. Obtain explicit human approval.

5. Call apply_change(proposal_id=..., approved=true).

6. The server checks for conflicts, writes once, reads back, verifies, and audits.

7. Use rollback_change to create a separately approved rollback proposal.

Read-only diagnostics

• get_detection_rules(camera="example_camera") reads detector types advertised by the camera. Pass kinds to probe specific types. Each result reports support independently and preserves readable configuration if schedule or linkage sub-resources are unavailable.

• get_camera_health, get_stream_profiles, get_image_settings, and get_storage_status expose operational state without allowing networking, accounts, firmware, or reset actions.

• get_audio_alarm and get_two_way_audio describe audible deterrence and talk-channel configuration. They do not play audio, open a talk session, or change camera state.

• get_intrusion_detection(camera="example_camera") returns field-detection enablement, regions, polygons, targets, sensitivity, arming schedule, and linkage methods.

• monitor_events(camera="example_camera", duration_seconds=15) watches the alert stream for a bounded period. Use event_types=["fielddetection"] to filter exact camera event names.

• get_warning_light(camera="example_camera") returns duration, frequency, and schedule. The reference V5.7.19 firmware does not advertise brightness or a standalone enabled flag.

Quality checks

uv run ruff check .
uv run mypy
uv run pytest

See CONFIGURATION.md, SECURITY.md, and DEVELOPMENT.md.

Project status and support

This project is not affiliated with or endorsed by Hikvision. Hikvision and ISAPI are used only to identify compatible products and protocols. Hardware and firmware behavior varies; unsupported or unknown features return unsupported_capability rather than being guessed.

Bug reports and contributions are welcome. Read CONTRIBUTING.md before submitting camera payloads or changes, and use SECURITY.md for vulnerabilities.

Licensed under the MIT License.