光学MCP

](https://pypi.org/project/optic-mcp/) ![Python 3.10+](https://www.python.org/downloads/) ![License: MIT](https://opensource.org/licenses/MIT)

一个模型上下文协议（MCP）服务器，为AI助手提供相机/视觉工具。连接到相机并捕获图像以供LLM使用。

视觉

OpticMCP旨在成为AI助手的通用相机接口，支持任何类型的相机：

USB摄像头 ✅
IP/网络摄像头 ✅ - RTSP、HLS、MJPEG流
屏幕捕获 ✅ - 桌面/显示器捕获
HTTP映像 ✅ - 从URL下载图像
QR/条形码解码 ✅ - 解码二维码和条形码
图像分析 ✅ - 元数据、统计数据、直方图、主色
图像比较 ✅ - SSIM、MSE、感知哈希、视觉差异
检测 ✅ - 人脸检测、运动检测、边缘检测
Raspberry Pi相机 （计划中）-CSI摄像头模块
移动摄像头 （计划中）-手机摄像头集成

特点

USB摄像头

list_cameras -扫描并列出所有可用的USB摄像头
保存图片 -捕获帧并直接保存到文件

摄像头流媒体

start_stream -开始将摄像头流式传输到localhost HTTP服务器（MJPEG）
停止流 -停止流式传输摄像头
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_监视器 -列出所有可用的监视器/显示器
screen_save_image -捕获监视器的完整屏幕截图
screen_save_region -捕捉屏幕的特定区域

HTTP映像

http_save_image -从任何URL下载并保存图像
http_check_image -检查URL是否指向有效图像

QR/条形码解码（需要libzbar）

解码器_qr -从图像中解码二维码
解码码 -解码条形码（EAN、UPC、Code128等）
decode_all -解码图像中的所有二维码和条形码
解码和匿名 -解码并保存带有边界框的带注释图像

图像分析

image_get-metadata -提取包含EXIF数据的图像元数据
image_get_stats -计算亮度、对比度、锐度
图像_直方图 -使用可选可视化生成颜色直方图
图像_主色调_颜色 -使用K-means聚类提取主色

图像比较

image_compare_ssim -使用结构相似性指数比较图像
image_compare_mse -使用均方误差比较图像
image_compare_hash -使用感知哈希（phash、dhash、ahash）比较图像
image_get_hash -为图像生成感知哈希
image_diff -创建视觉差异，突出差异
图像比较图表 -通过颜色直方图比较图像

检测

检测面 -使用Haar级联或DNN检测人脸
detect_faces_save -检测人脸并保存带注释的图像
检测运动 -检测两帧之间的运动
检测边界 -使用Canny、Sobel或拉普拉斯算子检测边缘
检测对象 -使用MobileNet SSD检测常见对象

需求

Python 3.10+
USB摄像头已连接到您的系统

安装

来自PyPI（推荐）

pip install optic-mcp

或与 uv:

uv pip install optic-mcp

来源

# Clone the repository
git clone https://github.com/Timorleiderman/OpticMCP.git
cd OpticMCP

# Install dependencies with uv
uv sync

用法

运行MCP服务器

如果从PyPI安装：

optic-mcp

或者使用uvx（无需安装）：

uvx optic-mcp

从源头运行

uv run optic-mcp

MCP配置

克劳德桌面

添加到您的Claude Desktop配置文件中：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json 窗户： %APPDATA%\Claude\claude_desktop_config.json

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

OpenCode

添加到您的 opencode.json （in .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)"
  }
]

保存图片

捕获帧并将其保存到磁盘。

参数：

file_path （str）-保存图像的路径
camera_index （int，默认值：0）-要从中捕获的相机索引

退货： 带有文件路径的成功消息

流媒体工具

将摄像头流式传输到本地HTTP服务器，以便在任何浏览器中实时查看。

start_stream

开始将摄像头流式传输到localhost 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流（可以嵌入其他应用程序中）

停止流

停止播放相机。

参数：

camera_index （int，默认值：0）-停止流式传输的相机索引

退货： 带状态的词典

list_streams

列出所有活动的摄像机流。

退货： 活动流信息列表，包括URL和端口

仪表板工具

start_dashboard

启动动态多摄像头仪表板服务器。仪表板会自动检测所有活动的摄像头流，并在响应式网格布局中显示它们。

参数：

port （int，默认值：9000）-为仪表板提供服务的端口

退货： 带有仪表板URL和状态的词典

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

用途：

使用以下命令启动一个或多个相机流 start_stream
使用以下命令启动仪表板 start_dashboard
打开 http://localhost:9000 在浏览器中
仪表板每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）-连接超时

退货： 包含流状态和属性（宽度、高度、fps、编解码器）的字典

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）-连接超时

退货： 包含流状态和属性（宽度、高度、fps、编解码器）的字典

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和content_type的词典

屏幕截图工具

screen_list_监视器

列出所有可用的监视器/显示器。

退货： 带有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）-连接超时

退货： 带状态、content_type和size_bytes的词典

QR/条形码工具

注：这些工具需要 libzbar 系统库。安装方式： brew install zbar （macOS）或 apt install libzbar0 （Linux）

解码器_qr

从图像文件中解码二维码。

参数：

file_path （str）-图像文件的路径

退货： 包含查找、计数和代码列表的词典

解码码

从图像文件中解码条形码（EAN、UPC、Code128等）。

参数：

file_path （str）-图像文件的路径

退货： 包含查找、计数和代码列表的词典

decode_all

解码图像文件中的所有二维码和条形码。

参数：

file_path （str）-图像文件的路径

退货： 包含查找、计数和代码列表的词典

解码和匿名

解码代码并保存带有边界框的带注释图像。

参数：

file_path （str）-输入图像的路径
output_path （str）-带注释的输出图像的路径

退货： 包含find、count、output_path和代码列表的词典

图像分析工具

image_get-metadata

从图像文件中提取元数据，包括尺寸、格式和EXIF数据。

参数：

file_path （str）-图像文件的路径

退货： 带宽度、高度、格式、模式、file_size_bytes和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-一）、锐度和is_grayscale的字典

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

图像_直方图

使用可选可视化计算每个通道（R、G、B）的颜色直方图。

参数：

file_path （str）-图像文件的路径
output_path （str，可选）-保存直方图可视化的路径

退货： 带通道（r、g、b 256值数组）和output_path（如果提供）的字典

图像_主色调_颜色

使用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 （浮点数，默认值：0.95）-相似性阈值

退货： 具有ssim_score（-1到1）、is_similar和阈值的词典

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

image_compare_mse

使用均方误差比较两个图像。

参数：

file_path_1 （str）-第一张图片的路径
file_path_2 （str）-第二张图片的路径

退货： 具有mse、is_identical和normalized_mse（0-1）的词典

image_compare_hash

使用感知哈希比较两个图像。

参数：

file_path_1 （str）-第一张图片的路径
file_path_2 （str）-第二张图片的路径
hash_type （str，默认值：“phash”）-哈希类型：“phath”、“dhash”或“ahash”

退货： 包含hash_1、hash_2、距离、is_similar和hash_type的字典

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

image_get_hash

为单个图像生成感知哈希。

参数：

file_path （str）-图像文件的路径
hash_type （str，默认值：“phash”）-哈希类型：“phath”、“dhash”或“ahash”

退货： 带有哈希（十六进制字符串）和hash_type的字典

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
}

图像比较图表

通过颜色直方图比较两个图像。

参数：

file_path_1 （str）-第一张图片的路径
file_path_2 （str）-第二张图片的路径
method （str，默认值：“correlation”）-方法：“correction”、“chi_square”、“interview”、“bhattacharyya”

退货： 带分数、方法和is_similar的词典

检测工具

检测面

使用Haar级联或DNN检测图像中的人脸。

参数：

file_path （str）-图像文件的路径
method （str，默认值：“haar”）-检测方法：“haal”（快速）或“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， default: “她”） - 检测方法：“她”或“dnn”

退货： 包含found、count、output_path和faces列表的字典

检测运动

比较两帧以检测它们之间的运动。

参数：

file_path_1 （str）-第一个（较早）图像的路径
file_path_2 （str）-第二张（稍后）图像的路径
threshold （浮动，默认值：25.0）-像素差阈值（0-255）

退货： 具有motion_detected、motion_percentage、motion_regions列表和changed_pixels的词典

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

检测边界

使用各种方法检测图像中的边缘。

参数：

file_path （str）-输入图像的路径
output_path （str）-保存边缘检测输出的路径
method （str，默认值：“canny”）-方法：“canni”、“sobel”或“laplacian”

退货： 带状态、output_path和方法的字典

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

检测对象

使用MobileNet SSD检测常见对象。

参数：

file_path （str）-图像文件的路径
confidence_threshold （浮点数，默认值：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之前在文件描述符级别抑制stderr，以防止此问题。

路线图

\[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 -视频录制功能

贡献

欢迎投稿！看贡献.md 作为指导方针。

许可证

麻省理工学院

Optic MCP

快速接入

详细介绍

光学MCP

视觉

特点

USB摄像头

摄像头流媒体

多摄像头仪表板

RTSP流

HLS流媒体（HTTP实时流媒体）

MJPEG流

屏幕捕获

HTTP映像

QR/条形码解码（需要libzbar）

图像分析

图像比较

检测

需求

安装

来自PyPI（推荐）

来源

用法

运行MCP服务器

从源头运行

MCP配置

克劳德桌面

OpenCode

其他MCP客户端

工具

list_cameras

保存图片

流媒体工具

start_stream

停止流

list_streams

仪表板工具

start_dashboard

stop_dashboard

RTSP工具

rtsp_save_image

rtsp_check_stream

HLS工具

hls_save_image

hls_check_stream

MJPEG工具

mjpeg_save_image

mjpeg_check_stream

屏幕截图工具

screen_list_监视器

screen_save_image

screen_save_region

HTTP图像工具

http_save_image

http_check_image

QR/条形码工具

解码器_qr

解码码

decode_all

解码和匿名

图像分析工具

image_get-metadata

image_get_stats

图像_直方图

图像_主色调_颜色

图像比较工具

image_compare_ssim

image_compare_mse

image_compare_hash

image_get_hash

image_diff

图像比较图表

检测工具

检测面

detect_faces_save

检测运动

检测边界

检测对象

技术说明

OpenCV+MCP兼容性