Opticmcp

🚀 OpticMCP

OpticMCP是一個模型上下文協議（MCP）服務器，為AI助手提供相機/視覺工具。它可以連接相機並捕獲圖像，供大語言模型（LLMs）使用。

🚀 快速開始

運行要求

• Python 3.10 及以上版本
• 系統連接有USB相機

運行方式

從 PyPI 安裝（推薦）

pip install optic-mcp

或者使用 uv：

uv pip install optic-mcp

安裝完成後，若從 PyPI 安裝，可使用以下命令啟動 MCP 服務器：

optic-mcp

或者使用 uvx（無需安裝）：

uvx optic-mcp

從源代碼運行

# 克隆倉庫
git clone https://github.com/Timorleiderman/OpticMCP.git
cd OpticMCP

# 使用 uv 安裝依賴
uv sync

# 運行服務
uv run optic-mcp

✨ 主要特性

OpticMCP旨在成為AI助手的通用相機接口，支持以下類型的相機：

• USB 相機 ✅
• IP/網絡相機 ✅ - 支持 RTSP、HLS、MJPEG 流
• 屏幕捕獲 ✅ - 支持桌面/顯示器捕獲
• HTTP 圖像 ✅ - 從 URL 下載圖像
• QR/條形碼解碼 ✅ - 解碼 QR 碼和條形碼
• 圖像分析 ✅ - 支持提取元數據、統計信息、生成直方圖、提取主色調
• 圖像比較 ✅ - 支持使用 SSIM、MSE、感知哈希、可視化差異等方法
• 檢測 ✅ - 支持人臉檢測、運動檢測、邊緣檢測
• 樹莓派相機（計劃中） - CSI 相機模塊
• 移動相機（計劃中） - 手機相機集成

具體功能

USB 相機

• list_cameras - 掃描並列出所有可用的 USB 相機
• save_image - 捕獲一幀並直接保存到文件

相機流

• start_stream - 開始將相機流傳輸到本地 HTTP 服務器（MJPEG 格式）
• stop_stream - 停止相機流傳輸
• list_streams - 列出所有活動的相機流

多相機儀表盤

• start_dashboard - 啟動一個動態儀表盤，以響應式網格佈局顯示所有活動的相機流
• stop_dashboard - 停止儀表盤服務器

RTSP 流

• rtsp_save_image - 從 RTSP 流中捕獲並保存一幀
• rtsp_check_stream - 驗證 RTSP 流並獲取其屬性

HLS 流（HTTP 即時流）

• hls_save_image - 從 HLS 流中捕獲並保存一幀
• hls_check_stream - 驗證 HLS 流並獲取其屬性

MJPEG 流

• mjpeg_save_image - 從 MJPEG 流（常見於 IP 相機、ESP32 - CAM）中捕獲一幀
• mjpeg_check_stream - 驗證 MJPEG 流的可用性

屏幕捕獲

• screen_list_monitors - 列出所有可用的顯示器
• screen_save_image - 捕獲顯示器的全屏截圖
• screen_save_region - 捕獲屏幕的特定區域

HTTP 圖像

• http_save_image - 從任何 URL 下載並保存圖像
• http_check_image - 檢查 URL 是否指向有效的圖像

QR/條形碼解碼（需要 libzbar）

• decode_qr - 從圖像中解碼 QR 碼
• decode_barcode - 解碼條形碼（EAN、UPC、Code128 等）
• decode_all - 從圖像中解碼所有 QR 碼和條形碼
• decode_and_annotate - 解碼並保存帶有邊界框的註釋圖像

圖像分析

• image_get_metadata - 提取圖像元數據，包括 EXIF 數據
• image_get_stats - 計算圖像的亮度、對比度、清晰度
• image_get_histogram - 生成顏色直方圖，可選擇可視化
• image_get_dominant_colors - 使用 K - means 聚類提取主色調

圖像比較

• image_compare_ssim - 使用結構相似性指數（SSIM）比較圖像
• image_compare_mse - 使用均方誤差（MSE）比較圖像
• image_compare_hash - 使用感知哈希（phash、dhash、ahash）比較圖像
• image_get_hash - 為圖像生成感知哈希
• image_diff - 創建可視化差異，突出顯示兩幅圖像的不同之處
• image_compare_histograms - 通過顏色直方圖比較圖像

檢測

• detect_faces - 使用 Haar 級聯或深度神經網絡（DNN）檢測人臉
• detect_faces_save - 檢測人臉並保存帶有邊界框的註釋圖像
• detect_motion - 比較兩幀圖像以檢測運動
• detect_edges - 使用 Canny、Sobel 或 Laplacian 方法檢測圖像邊緣
• detect_objects - 使用 MobileNet SSD 檢測常見物體

📦 安裝指南

從 PyPI 安裝（推薦）

pip install optic-mcp

或者使用 uv：

uv pip install optic-mcp

從源代碼安裝

# 克隆倉庫
git clone https://github.com/Timorleiderman/OpticMCP.git
cd OpticMCP

# 使用 uv 安裝依賴
uv sync

💻 使用示例

運行 MCP 服務器

從 PyPI 安裝後運行

optic-mcp

使用 uvx 運行（無需安裝）

uvx optic-mcp

從源代碼運行

uv run optic-mcp

MCP 配置

Claude Desktop

將以下內容添加到你的 Claude Desktop 配置文件中： macOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "optic-mcp": {
      "command": "uvx",
      "args": ["optic-mcp"]
    }
  }
}

OpenCode

將以下內容添加到你的 opencode.json 文件中（在項目目錄的 .opencode/ 或全局的 ~/.opencode/ 中）：

{
  "mcp": {
    "optic-mcp": {
      "type": "local",
      "command": ["uvx", "optic-mcp"]
    }
  }
}

其他 MCP 客戶端

使用 uvx（推薦 - 無需安裝）：

{
  "mcpServers": {
    "optic-mcp": {
      "command": "uvx",
      "args": ["optic-mcp"]
    }
  }
}

使用 pip 安裝：

{
  "mcpServers": {
    "optic-mcp": {
      "command": "optic-mcp"
    }
  }
}

從源代碼運行：

{
  "mcpServers": {
    "optic-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/OpticMCP", "optic-mcp"]
    }
  }
}

📚 詳細文檔

工具使用說明

list_cameras

掃描可用的 USB 相機（索引 0 - 9）並返回其狀態。

[
  {
    "index": 0,
    "status": "available",
    "backend": "AVFOUNDATION",
    "description": "Camera 0 (AVFOUNDATION)"
  }
]

save_image

捕獲一幀並保存到磁盤。 參數：

• file_path (str) - 圖像保存路徑
• camera_index (int, 默認值: 0) - 要捕獲圖像的相機索引

返回值： 包含文件路徑的成功消息

流工具

將相機流傳輸到本地 HTTP 服務器，以便在任何瀏覽器中即時查看。

start_stream

開始將相機流傳輸到本地 HTTP 服務器。流使用廣泛支持的 MJPEG 格式。 參數：

• camera_index (int, 默認值: 0) - 要流傳輸的相機索引
• port (int, 默認值: 8080) - 流服務的端口

返回值： 包含流 URL 和狀態的字典

{
  "status": "started",
  "camera_index": 0,
  "port": 8080,
  "url": "http://localhost:8080",
  "stream_url": "http://localhost:8080/stream"
}

使用方法：

• 在瀏覽器中打開 http://localhost:8080 以使用簡單 UI 查看流
• 使用 http://localhost:8080/stream 獲取原始 MJPEG 流（可嵌入其他應用程序）

stop_stream

停止相機流傳輸。 參數：

• camera_index (int, 默認值: 0) - 要停止流傳輸的相機索引

返回值： 包含狀態的字典

list_streams

列出所有活動的相機流。 返回值： 包含活動流信息（包括 URL 和端口）的列表

儀表盤工具

start_dashboard

啟動一個動態的多相機儀表盤服務器。儀表盤會自動檢測所有活動的相機流，並以響應式網格佈局顯示它們。 參數：

• port (int, 默認值: 9000) - 儀表盤服務的端口

返回值： 包含儀表盤 URL 和狀態的字典

{
  "status": "started",
  "port": 9000,
  "url": "http://localhost:9000"
}

使用方法：

1. 使用 start_stream 啟動一個或多個相機流。
2. 使用 start_dashboard 啟動儀表盤。
3. 在瀏覽器中打開 http://localhost:9000。
4. 儀表盤每 3 秒自動更新一次，以檢測新的/已移除的流。

stop_dashboard

停止儀表盤服務器。 返回值： 包含狀態的字典

RTSP 工具

注意： RTSP 功能尚未在真實的 RTSP 硬件/流上進行測試。雖然已實現，但可能需要針對特定相機供應商進行調整。

rtsp_save_image

從 RTSP 流中捕獲一幀並保存到磁盤。 參數：

• rtsp_url (str) - RTSP 流 URL（例如，rtsp://ip:554/stream）
• file_path (str) - 圖像保存路徑
• timeout_seconds (int, 默認值: 10) - 連接超時時間

返回值： 包含文件路徑的成功消息

rtsp_check_stream

驗證 RTSP 流並返回流信息。 參數：

• rtsp_url (str) - 要驗證的 RTSP 流 URL
• timeout_seconds (int, 默認值: 10) - 連接超時時間

返回值： 包含流狀態和屬性（寬度、高度、幀率、編解碼器）的字典

HLS 工具

hls_save_image

從 HLS 流中捕獲一幀並保存到磁盤。 參數：

• hls_url (str) - HLS 流 URL（通常以 .m3u8 結尾）
• file_path (str) - 圖像保存路徑
• timeout_seconds (int, 默認值: 30) - 連接超時時間

返回值： 包含文件路徑的成功消息

hls_check_stream

驗證 HLS 流並返回流信息。 參數：

• hls_url (str) - 要驗證的 HLS 流 URL
• timeout_seconds (int, 默認值: 30) - 連接超時時間

返回值： 包含流狀態和屬性（寬度、高度、幀率、編解碼器）的字典

MJPEG 工具

mjpeg_save_image

從 MJPEG 流（常見於 IP 相機、ESP32 - CAM、Arduino 相機）中捕獲一幀。 參數：

• mjpeg_url (str) - MJPEG 流 URL（例如，http://camera/video.mjpg）
• file_path (str) - 圖像保存路徑
• timeout_seconds (int, 默認值: 10) - 連接超時時間

返回值： 包含狀態、文件路徑和字節大小的字典

mjpeg_check_stream

驗證 MJPEG 流 URL。 參數：

• mjpeg_url (str) - 要驗證的 MJPEG 流 URL
• timeout_seconds (int, 默認值: 10) - 連接超時時間

返回值： 包含狀態、URL 和內容類型的字典

屏幕捕獲工具

screen_list_monitors

列出所有可用的顯示器。 返回值： 包含顯示器 ID、尺寸和位置的列表

screen_save_image

捕獲顯示器的全屏截圖。 參數：

• file_path (str) - 圖像保存路徑
• monitor (int, 默認值: 0) - 顯示器索引（0 表示所有顯示器組合）

返回值： 包含狀態、文件路徑和尺寸的字典

screen_save_region

捕獲屏幕的特定區域。 參數：

• file_path (str) - 圖像保存路徑
• x (int) - 左上角的 X 座標
• y (int) - 左上角的 Y 座標
• width (int) - 寬度（像素）
• height (int) - 高度（像素）

返回值： 包含狀態、文件路徑和區域詳細信息的字典

HTTP 圖像工具

http_save_image

從 URL 下載圖像並保存到磁盤。 參數：

• url (str) - 圖像 URL（http:// 或 https://）
• file_path (str) - 圖像保存路徑
• timeout_seconds (int, 默認值: 30) - 連接超時時間

返回值： 包含狀態、文件路徑、字節大小和內容類型的字典

http_check_image

使用 HEAD 請求驗證圖像 URL。 參數：

• url (str) - 要驗證的圖像 URL
• timeout_seconds (int, 默認值: 10) - 連接超時時間

返回值： 包含狀態、內容類型和字節大小的字典

QR/條形碼工具

注意： 這些工具需要 libzbar 系統庫。在 macOS 上使用 brew install zbar 安裝，在 Linux 上使用 apt install libzbar0 安裝。

decode_qr

從圖像文件中解碼 QR 碼。 參數：

• file_path (str) - 圖像文件路徑

返回值： 包含是否找到、數量和代碼列表的字典

decode_barcode

從圖像文件中解碼條形碼（EAN、UPC、Code128 等）。 參數：

• file_path (str) - 圖像文件路徑

返回值： 包含是否找到、數量和代碼列表的字典

decode_all

從圖像文件中解碼所有 QR 碼和條形碼。 參數：

• file_path (str) - 圖像文件路徑

返回值： 包含是否找到、數量和代碼列表的字典

decode_and_annotate

解碼代碼並保存帶有邊界框的註釋圖像。 參數：

• file_path (str) - 輸入圖像路徑
• output_path (str) - 註釋輸出圖像路徑

返回值： 包含是否找到、數量、輸出路徑和代碼列表的字典

圖像分析工具

image_get_metadata

從圖像文件中提取元數據，包括尺寸、格式和 EXIF 數據。 參數：

• file_path (str) - 圖像文件路徑

返回值： 包含寬度、高度、格式、模式、文件大小字節和 EXIF 字典的字典

{
  "width": 1920,
  "height": 1080,
  "format": "JPEG",
  "mode": "RGB",
  "file_size_bytes": 245678,
  "exif": {"Make": "Canon", "Model": "EOS R5", ...}
}

image_get_stats

計算圖像的基本統計信息，包括亮度、對比度和清晰度。 參數：

• file_path (str) - 圖像文件路徑

返回值： 包含亮度（0 - 1）、對比度（0 - 1）、清晰度和是否為灰度圖像的字典

{
  "brightness": 0.65,
  "contrast": 0.42,
  "sharpness": 2.35,
  "is_grayscale": false
}

image_get_histogram

計算每個通道（R、G、B）的顏色直方圖，可選擇可視化。 參數：

• file_path (str) - 圖像文件路徑
• output_path (str, 可選) - 保存直方圖可視化的路徑

返回值： 包含通道（r、g、b 數組，每個數組 256 個值）和輸出路徑（如果提供）的字典

image_get_dominant_colors

使用 K - means 聚類提取主色調。 參數：

• file_path (str) - 圖像文件路徑
• num_colors (int, 默認值: 5) - 要提取的顏色數量（1 - 20）

返回值： 包含顏色的 RGB 值、十六進制代碼和百分比的列表

{
  "colors": [
    {"rgb": [64, 128, 192], "hex": "#4080C0", "percentage": 35.2},
    {"rgb": [255, 255, 255], "hex": "#FFFFFF", "percentage": 28.1}
  ]
}

圖像比較工具

image_compare_ssim

使用結構相似性指數（SSIM）比較兩幅圖像。 參數：

• file_path_1 (str) - 第一幅圖像的路徑
• file_path_2 (str) - 第二幅圖像的路徑
• threshold (float, 默認值: 0.95) - 相似度閾值

返回值： 包含 SSIM 分數（-1 到 1）、是否相似和閾值的字典

{
  "ssim_score": 0.9823,
  "is_similar": true,
  "threshold": 0.95
}

image_compare_mse

使用均方誤差（MSE）比較兩幅圖像。 參數：

• file_path_1 (str) - 第一幅圖像的路徑
• file_path_2 (str) - 第二幅圖像的路徑

返回值： 包含 MSE、是否相同和歸一化 MSE（0 - 1）的字典

image_compare_hash

使用感知哈希比較兩幅圖像。 參數：

• file_path_1 (str) - 第一幅圖像的路徑
• file_path_2 (str) - 第二幅圖像的路徑
• hash_type (str, 默認值: "phash") - 哈希類型："phash"、"dhash" 或 "ahash"

返回值： 包含哈希 1、哈希 2、距離、是否相似和哈希類型的字典

{
  "hash_1": "8f0f0f0f0f0f0f0f",
  "hash_2": "8f0f0f0f0f0f0f0f",
  "distance": 0,
  "is_similar": true,
  "hash_type": "phash"
}

image_get_hash

為單幅圖像生成感知哈希。 參數：

• file_path (str) - 圖像文件路徑
• hash_type (str, 默認值: "phash") - 哈希類型："phash"、"dhash" 或 "ahash"

返回值： 包含哈希（十六進制字符串）和哈希類型的字典

image_diff

創建可視化差異，突出顯示兩幅圖像的不同之處。 參數：

• file_path_1 (str) - 參考圖像的路徑
• file_path_2 (str) - 比較圖像的路徑
• output_path (str) - 保存差異可視化的路徑
• threshold (int, 默認值: 30) - 像素差異閾值（0 - 255）

返回值： 包含狀態、輸出路徑、差異百分比和差異像素數的字典

{
  "status": "success",
  "output_path": "/path/to/diff.png",
  "diff_percentage": 12.5,
  "diff_pixels": 25600
}

image_compare_histograms

通過顏色直方圖比較兩幅圖像。 參數：

• file_path_1 (str) - 第一幅圖像的路徑
• file_path_2 (str) - 第二幅圖像的路徑
• method (str, 默認值: "correlation") - 方法："correlation"、"chi_square"、"intersection"、"bhattacharyya"

返回值： 包含分數、方法和是否相似的字典

檢測工具

detect_faces

使用 Haar 級聯或深度神經網絡（DNN）檢測圖像中的人臉。 參數：

• file_path (str) - 圖像文件路徑
• method (str, 默認值: "haar") - 檢測方法："haar"（快速）或 "dnn"（準確）

返回值： 包含是否找到、數量和人臉列表（包含 x、y、寬度、高度和置信度（僅 DNN））的字典

{
  "found": true,
  "count": 2,
  "faces": [
    {"x": 120, "y": 80, "width": 150, "height": 150},
    {"x": 400, "y": 100, "width": 140, "height": 140, "confidence": 0.95}
  ]
}

detect_faces_save

檢測人臉並保存帶有邊界框的註釋圖像。 參數：

• file_path (str) - 輸入圖像路徑
• output_path (str) - 保存註釋圖像的路徑
• method (str, 默認值: "haar") - 檢測方法："haar" 或 "dnn"

返回值： 包含是否找到、數量、輸出路徑和人臉列表的字典

detect_motion

比較兩幀圖像以檢測它們之間的運動。 參數：

• file_path_1 (str) - 第一幅（較早）圖像的路徑
• file_path_2 (str) - 第二幅（較晚）圖像的路徑
• threshold (float, 默認值: 25.0) - 像素差異閾值（0 - 255）

返回值： 包含是否檢測到運動、運動百分比、運動區域列表和變化像素數的字典

{
  "motion_detected": true,
  "motion_percentage": 15.3,
  "motion_regions": [
    {"x": 200, "y": 150, "width": 80, "height": 120}
  ],
  "changed_pixels": 31250
}

detect_edges

使用各種方法檢測圖像中的邊緣。 參數：

• file_path (str) - 輸入圖像路徑
• output_path (str) - 保存邊緣檢測輸出的路徑
• method (str, 默認值: "canny") - 方法："canny"、"sobel" 或 "laplacian"

返回值： 包含狀態、輸出路徑和方法的字典

{
  "status": "success",
  "output_path": "/path/to/edges.png",
  "method": "canny"
}

detect_objects

使用 MobileNet SSD 檢測常見物體。 參數：

• file_path (str) - 圖像文件路徑
• confidence_threshold (float, 默認值: 0.5) - 最小置信度（0 - 1）

返回值： 包含是否找到、數量和物體列表的字典

注意： 需要預訓練的 MobileNet SSD 模型文件。如果模型不可用，將返回空結果。

{
  "found": true,
  "count": 3,
  "objects": [
    {"class": "person", "confidence": 0.92, "x": 50, "y": 100, "width": 200, "height": 400},
    {"class": "car", "confidence": 0.87, "x": 300, "y": 250, "width": 180, "height": 120}
  ]
}

🔧 技術細節

OpenCV + MCP 兼容性

OpenCV 會將調試消息打印到標準錯誤輸出（stderr），這會破壞 MCP 的標準輸入輸出（stdio）通信。此服務器在導入 cv2 之前在文件描述符級別抑制了標準錯誤輸出，以防止此問題。

📄 許可證

本項目採用 MIT 許可證。

貢獻說明

歡迎貢獻代碼！請參閱 CONTRIBUTING.md 獲取指南。

路線圖

• [x] v0.1.0 - 通過 OpenCV 支持 USB 相機
• [x] v0.2.0 - 支持 IP 相機（RTSP 和 HLS 流）
• [x] v0.3.0 - 具有即時流的多相機儀表盤
• [x] v0.4.0 - 屏幕捕獲、MJPEG 流、HTTP 圖像、QR/條形碼解碼
• [x] v0.5.0 - 圖像分析和比較工具（元數據、統計信息、SSIM、哈希、差異）
• [x] v0.6.0 - 檢測工具（人臉檢測、運動檢測、邊緣檢測）
• [ ] v0.7.0 - 相機配置（分辨率、格式等）
• [ ] v0.8.0 - 視頻錄製功能