Hikvision CCTV MCP

MCP server สำหรับให้ MCP client (เช่น Codex หรือ Claude Desktop) จัดการ Hikvision NVR และ IP camera ผ่าน Hikvision ISAPI โดยใช้ HTTP Digest authentication

ใช้กับ NVR/กล้องที่ผู้ใช้งานมีสิทธิ์ดูแลเท่านั้น การเพิ่ม/ลบกล้อง, สร้างผู้ใช้ และ reboot ส่งผลกับระบบจริง

ความสามารถ

Tool	การทำงาน	ผลกระทบ
hikvision_get_device_info	ดูชื่ออุปกรณ์ รุ่น firmware และ serial number	อ่านอย่างเดียว
hikvision_probe_capabilities	ตรวจ endpoint/capability ที่ firmware รุ่นนี้รองรับ	อ่านอย่างเดียว
hikvision_list_camera_channels	แสดงช่องกล้องใน NVR และ online/offline	อ่านอย่างเดียว
hikvision_get_channel_status	ตรวจสถานะทุกช่อง หรือช่องเดียว	อ่านอย่างเดียว
hikvision_rename_nvr_channel	เปลี่ยนชื่อ channel ที่แสดงบน NVR	ต้อง confirm=true
hikvision_set_camera_osd_name	เปลี่ยนข้อความ/ชื่อ OSD ที่ภาพจากกล้อง	ต้อง confirm=true
hikvision_add_ip_camera	เพิ่ม Hikvision/ONVIF IP camera ในช่อง NVR	เปลี่ยน config
hikvision_remove_ip_camera	ลบกล้องออกจากช่อง NVR	ต้อง confirm=true
hikvision_list_users	ดูบัญชีผู้ใช้ local บนอุปกรณ์	อ่านอย่างเดียว
hikvision_create_user	สร้างบัญชี Administrator/Operator/User	เปลี่ยน config
hikvision_get_recent_events	ขอ event/alarm notification stream	อ่านอย่างเดียว*
hikvision_reboot_device	รีบูต NVR หรือกล้อง	ต้อง confirm=true

* ความสามารถ event แตกต่างกันตามรุ่นและ firmware; บางอุปกรณ์ไม่รองรับ endpoint นี้ หรือใช้เป็น live alert stream แทน event history

ความต้องการ

• Python 3.10 ขึ้นไป
• เครื่องที่รัน MCP เข้าถึง IP/port ของ NVR หรือกล้องได้
• บัญชี Hikvision ที่มีสิทธิ์ตามงานที่เรียก
• แนะนำให้เปิด HTTPS บนอุปกรณ์และใช้ certificate ที่เชื่อถือได้

ติดตั้งบน Windows

git clone https://github.com/humyai99/mcp-cctv.git D:\MCP\mcp-cctv
cd D:\MCP\mcp-cctv
py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -r requirements.txt
Copy-Item .env.example .env

แก้ค่าใน .env ตาม NVR/กล้องของคุณ:

HIKVISION_HOST=192.168.10.5
HIKVISION_USERNAME=admin
HIKVISION_PASSWORD=your-secret-password
HIKVISION_USE_HTTPS=true
HIKVISION_VERIFY_TLS=true
HIKVISION_ALLOWED_NETWORKS=192.168.10.0/24

ไฟล์ .env ถูก ignore จาก Git และ server ไม่โหลดไฟล์นี้อัตโนมัติ เพื่อไม่ให้เกิดการเก็บ credentials โดยไม่ตั้งใจ ให้ client ส่ง environment variables โดยตรง (แนะนำ) หรือโหลดชั่วคราวใน PowerShell:

Get-Content .env | Where-Object { $_ -and -not $_.StartsWith('#') } | ForEach-Object {
  $name, $value = $_ -split '=', 2
  Set-Item -Path "Env:$name" -Value $value
}
python server.py

server.py ใช้ MCP stdio transport จึงจะรอ client เชื่อมต่ออยู่ตามปกติ ไม่ใช่ HTTP web service

MCP tools ใช้ฟิลด์ตรงระดับบนสุด เช่น { "conn": { ... } } หรือ { "channel_id": 4 } เพื่อให้ Hermes Agent เรียกใช้งานได้โดยตรง

ตั้งค่า MCP client

เพิ่ม server นี้ลงใน MCP configuration ของ client โดยใช้ Python ใน virtual environment ที่สร้างไว้:

{
  "mcpServers": {
    "hikvision-cctv": {
      "command": "D:\\MCP\\mcp-cctv\\.venv\\Scripts\\python.exe",
      "args": ["D:\\MCP\\mcp-cctv\\server.py"],
      "env": {
        "HIKVISION_HOST": "192.168.10.5",
        "HIKVISION_USERNAME": "admin",
        "HIKVISION_PASSWORD": "your-secret-password",
        "HIKVISION_USE_HTTPS": "true",
        "HIKVISION_VERIFY_TLS": "true",
        "HIKVISION_ALLOWED_NETWORKS": "192.168.10.0/24"
      }
    }
  }
}

หากมีหลาย NVR สามารถตั้ง MCP server คนละชื่อและใส่ environment แยกกัน หรือส่ง object conn พร้อม host, username, password, use_https ในแต่ละ tool call ได้

ใช้กับ Hermes Agent

รองรับโดยตรงผ่าน MCP stdio. Hermes ไม่ส่ง environment variables ของ shell ทั้งหมดไปยัง MCP subprocess เพื่อป้องกัน secrets รั่วไหล ดังนั้นโปรเจกต์นี้มี run-hermes.ps1 สำหรับโหลดค่าจาก .env เฉพาะตอนเริ่ม server

หลังจากติดตั้ง Python dependencies และสร้าง .env ตามขั้นตอนข้างต้น ให้เพิ่มเข้า Hermes เพียงครั้งเดียว:

hermes mcp add hikvision-cctv --command powershell.exe --args -NoProfile -ExecutionPolicy Bypass -File D:\MCP\mcp-cctv\run-hermes.ps1

ตรวจสอบการเชื่อมต่อ:

hermes mcp list
hermes mcp test hikvision-cctv

หากแก้ .env ให้ reload/restart Hermes session แล้วเรียก hermes mcp test hikvision-cctv อีกครั้ง. Hermes จะเห็น tools ในชื่อกลุ่ม hikvision-cctv และเรียกใช้งานผ่านบทสนทนาได้

Hermes Agent บน NVIDIA DGX Spark (Linux)

MCP server ต้องถูกติดตั้งและรันบน เครื่อง DGX Spark เดียวกับ Hermes Agent (ไม่ใช่ Windows PC ที่ใช้แก้โค้ด). SSH เข้า DGX Spark แล้วรัน:

git clone https://github.com/humyai99/mcp-cctv.git ~/mcp-cctv
cd ~/mcp-cctv
python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install -r requirements.txt
cp .env.example .env
chmod 600 .env
chmod +x run-hermes.sh

แก้ ~/mcp-cctv/.env ใส่ IP, username และ password ของ Hikvision แล้วลงทะเบียนกับ Hermes:

hermes mcp add hikvision-cctv --command bash --args ~/mcp-cctv/run-hermes.sh
hermes mcp test hikvision-cctv

หากชื่อ hikvision-cctv มีอยู่แล้ว ให้ลบก่อนแล้วเพิ่มใหม่:

hermes mcp remove hikvision-cctv
hermes mcp add hikvision-cctv --command bash --args ~/mcp-cctv/run-hermes.sh

เริ่ม Hermes Agent session ใหม่หลังการเพิ่ม MCP. สำคัญ: DGX Spark ต้องมี network route/firewall ที่เข้าถึง NVR/camera ได้ และ HIKVISION_ALLOWED_NETWORKS ต้องครอบคลุม IP ของอุปกรณ์นั้น

วิธีใช้งาน

เริ่มต้นด้วยการเรียก hikvision_get_device_info เพื่อทดสอบ network, HTTPS และ credentials ก่อนเสมอ

สำหรับรุ่นที่ไม่แน่ใจ ให้เรียก hikvision_probe_capabilities ก่อน เครื่องมือจะตรวจ endpoint มาตรฐานหลายชุดและรายงานว่า endpoint ใดตอบ 200, ไม่รองรับ 404 หรือถูกจำกัดสิทธิ์ 403 จากนั้นจึงเลือกใช้ tool ที่เหมาะกับอุปกรณ์

ตรวจดูสถานะกล้อง

เรียก hikvision_list_camera_channels เพื่อดูทุกช่อง หรือ hikvision_get_channel_status พร้อม { "channel_id": 4 } เพื่อตรวจช่องเดียว

เปลี่ยนชื่อกล้องทั้งบน NVR และบนภาพจากกล้อง

ชื่อทั้งสองส่วนแยกกัน: ชื่อ channel ของ NVR ใช้เพื่อแสดงใน live view/รายการกล้อง ส่วนชื่อ OSD คือข้อความที่ฝังลงในภาพที่ตัวกล้องส่งออกมา

เปลี่ยนชื่อ channel บน NVR:

{ "channel_id": 4, "new_name": "ประตูหน้า", "confirm": true }

เปลี่ยน OSD บนตัวกล้อง: เรียก hikvision_set_camera_osd_name พร้อม conn ที่ชี้ไปยัง IP และ credentials ของกล้องโดยตรง ไม่ใช่ NVR:

{
  "conn": {
    "host": "192.168.10.101",
    "username": "admin",
    "password": "camera-password",
    "use_https": true
  },
  "camera_channel_id": 1,
  "text_overlay_id": 1,
  "new_name": "ประตูหน้า",
  "enabled": true,
  "confirm": true
}

บางรุ่นไม่รองรับ text overlay endpoint หรือใช้ overlay slot คนละหมายเลข; หากได้รับ endpoint is unavailable ให้ตรวจ firmware/capability ของกล้องก่อน

เพิ่มกล้อง IP

ตรวจช่องว่างก่อน แล้วเรียก hikvision_add_ip_camera ตัวอย่าง input:

{
  "channel_id": 4,
  "camera_ip": "192.168.10.101",
  "camera_port": 80,
  "protocol_type": "HIKVISION",
  "camera_username": "admin",
  "camera_password": "camera-password"
}

ใช้ "protocol_type": "ONVIF" สำหรับกล้อง third-party ที่เปิด ONVIF แล้ว กล้องต้องเปิดอยู่ เข้าถึงได้จาก NVR และมี credentials ถูกต้อง

ลบกล้อง

ตรวจ channel ID ให้แน่ใจก่อน จากนั้นเรียก:

{ "channel_id": 4, "confirm": true }

จัดการผู้ใช้

เรียก hikvision_list_users เพื่อดูบัญชีปัจจุบัน หรือสร้างผู้ใช้ด้วย:

{
  "new_username": "technician",
  "new_password": "StrongPassword123",
  "user_level": "Operator"
}

ค่า user_level ที่รองรับคือ Administrator, Operator, และ User ควรเลือกสิทธิ์ต่ำสุดที่เพียงพอต่อหน้าที่

Reboot

เรียก hikvision_reboot_device ด้วย { "confirm": true } เท่านั้น การ reboot NVR จะทำให้ live view และการบันทึกถูกรบกวนชั่วคราว

ความปลอดภัย

• อย่า commit .env หรือส่งรหัสผ่านเข้า GitHub
• ใช้ HTTPS (HIKVISION_USE_HTTPS=true) และตรวจ certificate (HIKVISION_VERIFY_TLS=true) ใน production
• ถ้าอุปกรณ์ใช้ self-signed certificate ให้ติดตั้ง CA ที่เชื่อถือได้เป็นทางเลือกแรก; การตั้ง HIKVISION_VERIFY_TLS=false มีความเสี่ยง
• กำหนด HIKVISION_ALLOWED_NETWORKS เพื่ออนุญาตเฉพาะ CIDR ที่คาดหมาย เช่น 192.168.10.0/24
• จำกัด firewall ให้เฉพาะเครื่อง MCP ที่จำเป็นต้องเข้าถึง NVR/camera
• action ที่ทำลายข้อมูลต้องส่ง confirm=true แต่ยังควรตรวจ input ทุกครั้งก่อนยืนยัน

การแก้ปัญหา

ข้อความผิดพลาด	สาเหตุ/แนวทาง
authentication failed	ตรวจ username/password และสิทธิ์บัญชี
could not connect	ตรวจ IP, port, VLAN/firewall และค่า HTTP/HTTPS
endpoint is unavailable	รุ่นหรือ firmware นั้นไม่รองรับ ISAPI endpoint; อัปเดต firmware หรือดูคู่มือรุ่นนั้น
host is not allowed	เพิ่ม IP/subnet ที่ถูกต้องใน HIKVISION_ALLOWED_NETWORKS
TLS/certificate error	ใช้ certificate ที่ถูกต้อง หรือแก้ไข trust store ของเครื่องที่รัน MCP

ข้อจำกัด

Hikvision ISAPI มีความแตกต่างตามรุ่น, region และ firmware โดยเฉพาะ Input Proxy, ผู้ใช้ และ event endpoints จึงควรทดสอบบนอุปกรณ์จริงก่อนใช้งาน production.