# 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

```powershell
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/กล้องของคุณ:

```dotenv
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:

```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 ที่สร้างไว้:

```json
{
  "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 เพียงครั้งเดียว:

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

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

```powershell
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 แล้วรัน:

```bash
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:

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

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

```bash
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:

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

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

```json
{
  "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:

```json
{
  "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 ให้แน่ใจก่อน จากนั้นเรียก:

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

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

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

```json
{
  "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.