🚀 OpenCV MCP 服务器

为 AI 助手提供强大的 OpenCV 计算机视觉功能的 MCP 服务器。

🔍 简介

OpenCV MCP 服务器是一个 Python 包，通过模型上下文协议 (MCP) 提供 OpenCV 的图像和视频处理功能。这使得 AI 助手和语言模型能够访问强大的计算机视觉工具，用于从基本图像操作到高级对象检测和跟踪的各种任务。

借助 OpenCV MCP 服务器，AI 系统可以：

• 处理和分析各种格式的图像
• 执行实时对象检测和跟踪
• 从视觉数据中提取有意义的信息
• 使用高级算法增强和转换图像
• 通过逐帧分析处理视频内容

✨ 特性

• 📸 基本图像处理和操作（读取、保存、转换）
• 🖼️ 图像处理和增强（调整大小、裁剪、应用滤镜）
• 📊 边缘检测和轮廓分析
• 🧠 高级计算机视觉功能（特征检测、对象检测）
• 😃 人脸检测和识别
• 🎬 视频处理和分析（帧提取、运动检测）
• 🔍 视频中的对象跟踪
• 📹 摄像头集成，用于实时对象检测

📊 演示示例

边缘检测

人脸检测

统计分析

视频处理

原始视频示例

轮廓检测处理

应用于上述原始视频的轮廓检测处理示例

📦 安装

pip install opencv-mcp-server

用于开发：

# 克隆仓库
git clone https://github.com/yourusername/opencv-mcp-server.git
cd opencv-mcp-server

# 创建一个虚拟环境
python -m venv .venv
source .venv/bin/activate  # 在 Windows 上：.venv\Scripts\activate

# 安装依赖
pip install -e .

🔧 用法

在 Claude Desktop 中使用

添加到您的 Claude Desktop 配置：

{
    "tools": {
        "opencv": {
            "command": "uvx",
            "args": [
                "opencv-mcp-server"
            ]
        }
    }
}

基本 Python 用法

from opencv_mcp_server import opencv_client

# 初始化客户端
client = opencv_client.OpenCVClient()

# 使用工具
result = client.resize_image(
    image_path="input.jpg",
    width=800,
    height=600
)

高级对象检测示例

由于所有必需的模型都已在 OPENCV_DNN_MODELS_DIR 中配置，因此您可以使用对象检测而无需指定模型路径：

# 使用预配置的 YOLO 模型检测对象
result = detect_objects_tool(
    image_path="street.jpg",
    confidence_threshold=0.5,
    nms_threshold=0.4
)

配置

可以使用环境变量配置服务器：

• MCP_TRANSPORT: 传输方法（默认值：“stdio”）
• OPENCV_DNN_MODELS_DIR: 用于存储 DNN 模型的目录（默认值：“models”）
• CV_HAAR_CASCADE_DIR: 用于存储 Haar 级联文件的目录（可选）

🧠 模型文件设置

计算机视觉和对象检测工具需要预训练的模型才能正常运行。这些模型应放置在 OPENCV_DNN_MODELS_DIR 环境变量指定的目录中（默认值：“./models”）。

必需的模型

以下模型已预先配置：

• 人脸检测（DNN 方法）

  • deploy.prototxt - 人脸检测配置
  • res10_300x300_ssd_iter_140000.caffemodel - 人脸检测模型权重

• 对象检测 (YOLO)

  • yolov3.weights - YOLO 模型权重
  • yolov3.cfg - YOLO 配置文件
  • coco.names - 检测到的对象的类名

模型用法

• 当指定 method="dnn" 时，detect_faces_tool 使用 DNN 模型
• detect_objects_tool 使用 YOLO 模型进行通用对象检测

对于那些需要下载这些模型的人，请参阅“安装”部分或访问：

• YOLO 模型：https://pjreddie.com/darknet/yolo/
• 人脸检测模型：https://github.com/opencv/opencv_3rdparty/tree/dnn_samples_face_detector_20170830

🧰 可用工具

OpenCV MCP 服务器提供范围广泛的计算机视觉工具，这些工具分为四个类别：

📸 图像基础

这些工具提供基本的图像操作功能：

• save_image_tool: 将图像保存到文件

  • 参数：path_in（输入图像路径），path_out（输出文件路径）
  • 返回：图像保存状态和路径信息
  • 示例：save_image_tool(path_in="processed.jpg", path_out="final.jpg")

• convert_color_space_tool: 在颜色空间之间转换图像（BGR、RGB、GRAY、HSV 等）

  • 参数：image_path、source_space、target_space
  • 返回：转换后的图像信息和路径
  • 示例：convert_color_space_tool(image_path="image.jpg", source_space="BGR", target_space="HSV")

• resize_image_tool: 将图像调整为特定尺寸

  • 参数：image_path、width、height、interpolation（可选）
  • 返回：调整大小后的图像信息和路径
  • 示例：resize_image_tool(image_path="large.jpg", width=800, height=600)

• crop_image_tool: 从图像中裁剪一个区域

  • 参数：image_path、x、y、width、height
  • 返回：裁剪后的图像信息和路径
  • 示例：crop_image_tool(image_path="scene.jpg", x=100, y=150, width=300, height=200)

• get_image_stats_tool: 获取有关图像的统计信息

  • 参数：image_path、channels（布尔值，默认值：true）
  • 返回：图像统计信息和直方图可视化
  • 示例：get_image_stats_tool(image_path="photo.jpg", channels=True)

🖼️ 图像处理

这些工具提供高级图像处理和转换功能：

• apply_filter_tool: 将各种滤镜应用于图像（模糊、高斯、中值、双边）

  • 参数：image_path、filter_type、kernel_size 和特定于滤镜的参数
  • 返回：已过滤的图像和滤镜信息
  • 示例：apply_filter_tool(image_path="noisy.jpg", filter_type="gaussian", kernel_size=5)

• detect_edges_tool: 使用不同的方法（Canny、Sobel、Laplacian、Scharr）检测图像中的边缘

  • 参数：image_path、method、阈值参数和特定于方法的参数
  • 返回：边缘检测到的图像和方法信息
  • 示例：detect_edges_tool(image_path="objects.jpg", method="canny", threshold1=100, threshold2=200)

• apply_threshold_tool: 将阈值应用于图像（二进制、自适应等）

  • 参数：image_path、threshold_type、阈值和特定于方法的参数
  • 返回：阈值化的图像和阈值信息
  • 示例：apply_threshold_tool(image_path="scan.jpg", threshold_type="binary", threshold_value=127)

• detect_contours_tool: 检测并可选择在图像中绘制轮廓

  • 参数：image_path、mode、method、绘图参数
  • 返回：带有轮廓的图像和轮廓信息
  • 示例：detect_contours_tool(image_path="shapes.jpg", mode="external", method="simple")

• find_shapes_tool: 在图像中查找基本形状（圆形、线条）

  • 参数：image_path、shape_type、特定于形状的参数
  • 返回：带有形状的图像和形状信息
  • 示例：find_shapes_tool(image_path="geometry.jpg", shape_type="circles", min_radius=10)

• match_template_tool: 在图像中查找模板

  • 参数：image_path、template_path、匹配参数
  • 返回：带有匹配项的图像和匹配信息
  • 示例：match_template_tool(image_path="scene.jpg", template_path="object.jpg", threshold=0.8)

🧠 计算机视觉

这些工具提供高级计算机视觉功能：

• detect_features_tool: 使用 SIFT、ORB、BRISK 等方法检测图像中的特征

  • 参数：image_path、method、max_features、绘图参数
  • 返回：带有关键点和特征信息的图像
  • 示例：detect_features_tool(image_path="landmark.jpg", method="sift", max_features=500)

• match_features_tool: 匹配两个图像之间的特征

  • 参数：image1_path、image2_path、method、匹配参数
  • 返回：带有匹配项的图像和匹配信息
  • 示例：match_features_tool(image1_path="scene1.jpg", image2_path="scene2.jpg", method="sift")

• detect_faces_tool: 使用 Haar 级联或 DNN 检测图像中的人脸

  • 参数：image_path、method、特定于方法的参数
  • 返回：带有面部和面部信息的图像
  • 示例：detect_faces_tool(image_path="group.jpg", method="haar", min_neighbors=5)

• detect_objects_tool: 使用预训练的 DNN 模型（例如，YOLO）检测对象

  • 参数：image_path、模型路径、检测参数
  • 返回：带有对象和对象信息的图像
  • 示例：detect_objects_tool(image_path="street.jpg", confidence_threshold=0.5)

🎬 视频处理

这些工具提供视频分析和处理功能：

• extract_video_frames_tool: 从视频文件中提取帧

  • 参数：video_path、帧选择参数
  • 返回：提取的帧信息和路径
  • 示例：extract_video_frames_tool(video_path="clip.mp4", start_frame=0, step=10, max_frames=20)

• detect_motion_tool: 检测两个帧之间的运动

  • 参数：frame1_path、frame2_path、检测参数
  • 返回：运动检测结果和可视化
  • 示例：detect_motion_tool(frame1_path="frame1.jpg", frame2_path="frame2.jpg", threshold=25)

• track_object_tool: 跨视频帧跟踪对象

  • 参数：video_path、initial_bbox、跟踪参数
  • 返回：跟踪结果和提取的帧
  • 示例：track_object_tool(video_path="tracking.mp4", initial_bbox=[100, 100, 50, 50])

• combine_frames_to_video_tool: 将帧组合到视频文件中

  • 参数：frame_paths、output_path、视频参数
  • 返回：视频创建结果
  • 示例：combine_frames_to_video_tool(frame_paths=["frame1.jpg", "frame2.jpg"], output_path="output.mp4")

• create_mp4_from_video_tool: 将视频文件转换为 MP4 格式

  • 参数：video_path、output_path、转换参数
  • 返回：转换结果，包括 MP4 路径
  • 示例：create_mp4_from_video_tool(video_path="input.avi", output_path="output.mp4")

• detect_video_objects_tool: 检测视频中的对象并创建检测结果视频

  • 参数：video_path、模型路径、检测参数
  • 返回：对象检测结果和输出视频路径
  • 示例：detect_video_objects_tool(video_path="traffic.mp4", confidence_threshold=0.5)

• detect_camera_objects_tool: 从计算机的摄像头检测对象并保存到视频

  • 参数：camera_id、录制参数、模型路径、检测参数
  • 返回：对象检测结果和输出视频路径
  • 示例：detect_camera_objects_tool(camera_id=0, duration=30, confidence_threshold=0.5)

📝 高级用法示例

📸 基本图像处理

# 调整图像大小
result = resize_image_tool(
    image_path="input.jpg",
    width=800,
    height=600
)
# 访问调整大小后的图像路径
resized_image_path = result["output_path"]

# 应用高斯模糊滤镜
result = apply_filter_tool(
    image_path="input.jpg",
    filter_type="gaussian",
    kernel_size=5,
    sigma=1.5
)

🧠 对象检测

# 使用 YOLO 检测图像中的对象
result = detect_objects_tool(
    image_path="scene.jpg",
    confidence_threshold=0.5,
    nms_threshold=0.4
)
# 访问检测到的对象
objects = result["objects"]
for obj in objects:
    print(f"Detected {obj['class_name']} with confidence {obj['confidence']}")

🎬 视频分析

# 从视频中提取帧
result = extract_video_frames_tool(
    video_path="input.mp4",
    start_frame=0,
    step=10,
    max_frames=10
)
# 访问提取的帧
frames = result["frames"]

# 检测视频中的对象
result = detect_video_objects_tool(
    video_path="input.mp4",
    confidence_threshold=0.5,
    frame_step=5
)

🔄 链式操作

可以通过使用一个工具的 output_path 作为另一个工具的输入来将工具链接在一起：

# 首先调整图像大小
result1 = resize_image_tool(
    image_path="input.jpg",
    width=800,
    height=600
)

# 然后将边缘检测应用于调整大小后的图像
result2 = detect_edges_tool(
    image_path=result1["output_path"],
    method="canny",
    threshold1=100,
    threshold2=200
)

# 最后检测边缘检测图像中的轮廓
result3 = detect_contours_tool(
    image_path=result2["output_path"],
    mode="external",
    method="simple"
)

🔍 实际应用

OpenCV MCP 服务器可用于广泛的应用：

• 🤖 自主系统：基于视觉的导航和障碍物检测
• 🚗 交通分析：车辆计数、速度估计和车牌识别
• 🔐 安全系统：运动检测和面部识别
• 📱 增强现实：特征跟踪和姿势估计
• 🏥 医学成像：组织分割和异常检测
• 🏭 工业检测：缺陷检测和质量控制
• 🖼️ 数字艺术：图像过滤和转换
• 🎲 游戏：手势识别和玩家跟踪

🗺️ 路线图

计划用于 OpenCV MCP 服务器的未来增强功能：

• 📊 附加的统计分析工具
• 🧬 高级分割算法
• 🧠 与机器学习模型集成
• 🌐 3D 视觉功能
• 📱 移动友好的处理选项
• ⚡ 实时处理的性能优化

🤝 贡献

欢迎贡献！请随时提交 Pull Request。

1. Fork 该项目
2. 创建您的功能分支 (git checkout -b feature/amazing-feature)
3. 提交您的更改 (git commit -m 'Add some amazing feature')
4. 推送到该分支 (git push origin feature/amazing-feature)
5. 打开一个 Pull Request

📜 许可证

MIT 许可证 - 有关详细信息，请参阅 LICENSE 文件。

📞 联系方式

如有问题或反馈，请在 GitHub 存储库上打开一个 issue。

---

使用 OpenCV 和 Python 构建，充满 ❤️。