OpenCV MCP Server for Image and Video Processing

Overview

OpenCV MCP Server exposes OpenCV’s image and video processing capabilities over the Model Context Protocol (MCP). It wraps common computer vision tasks — image IO and transforms, DNN-based object and face detection, contour/edge analysis, and frame-by-frame video processing — into a small MCP server so language models and agent frameworks can call vision tools programmatically.

By running as an MCP server (default transport: stdio) the project makes OpenCV functions accessible to assistants, chatbots, or any MCP-capable client without embedding OpenCV code directly. This is useful for rapid prototyping, automating visual analysis pipelines, and adding image/video capabilities to LLM-based agents with minimal integration effort.

Features

• Basic image IO: read, write, convert color spaces
• Image transforms: resize, crop, filters, histogram/statistics
• Edge detection, contour analysis and feature extraction
• Face detection (DNN + optional Haar cascade)
• Object detection using pre-configured YOLO DNN models
• Video processing: frame extraction, motion detection, per-frame analysis
• Object tracking across frames
• Camera integration for real-time detection
• Configurable via environment variables (MCP transport, model directories)

Installation / Configuration

Install from PyPI:

pip install opencv-mcp-server

Run from a cloned repository for development:

git clone https://github.com/GongRzhe/opencv-mcp-server.git
cd opencv-mcp-server
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e .

Environment variables (optional):

# Default transport is "stdio"
export MCP_TRANSPORT=stdio

# Directory that stores DNN / model files (default: ./models)
export OPENCV_DNN_MODELS_DIR=./models

# Optional directory for Haar cascade XMLs
export CV_HAAR_CASCADE_DIR=./haarcascades

Integration example (Claude Desktop JSON):

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

If using the above, install uv/uvx as needed (example for macOS Homebrew):

brew install uv

Required model files

Place pre-trained models in the directory pointed to by OPENCV_DNN_MODELS_DIR (default: ./models).

Download sources:

• YOLO: https://pjreddie.com/darknet/yolo/
• OpenCV face DNN: https://github.com/opencv/opencv_3rdparty/tree/dnn_samples_face_detector_20170830

Available Tools / Resources

Common MCP tools exposed by the server (names and key parameters):

• save_image_tool
  • params: path_in, path_out
• convert_color_space_tool
  • params: image_path, source_space, target_space
• resize_image_tool
  • params: image_path, width, height, interpolation
• crop_image_tool
  • params: image_path, x, y, width, height
• detect_faces_tool
  • params: image_path, method (“dnn”|“haar”), confidence_threshold
• detect_objects_tool
  • params: image_path, model (“yolov3”), confidence_threshold, nms_threshold
• video_process_tool
  • params: video_path, frame_rate, operations (list)
• track_objects_tool
  • params: video_path, initial_boxes, tracker_type

Each tool returns structured JSON containing outputs (bounding boxes, paths to output images/videos, statistics). Use the official client helper to simplify calls from Python.

Quick Python examples

Resize an image:

from opencv_mcp_server import opencv_client

client = opencv_client.OpenCVClient()
result = client.resize_image(image_path="input.jpg", width=800, height=600)
print(result)  # JSON with output path and metadata

Run object detection (uses models in OPENCV_DNN_MODELS_DIR):

result = client.detect_objects_tool(image_path="street.jpg",
                                    confidence_threshold=0.5,
                                    nms_threshold=0.4)
# result contains detected classes, confidences and bounding boxes

Use Cases

• Web image pipeline: automatically resize and re-encode uploaded photos for thumbnails and responsive delivery with resize_image_tool + convert_color_space_tool.
• Photo app face tagging: detect_faces_tool to find faces, then crop_image_tool to generate profile pictures or pass face crops to an embedding/recognition pipeline.
• Security/motion detection: video_process_tool to detect motion across frames and track_objects_tool to follow moving persons/vehicles in recorded footage.
• Agent-assisted visual tasks: attach the MCP server to an LLM-based assistant so it can analyze screenshots, extract statistics (edge/contour analysis), or annotate frames during a debugging/annotation workflow.

Notes

• The server defaults to stdio MCP transport, making it simple to wire into many MCP clients; other transports can be configured via MCP_TRANSPORT.
• Ensure required DNN model files are downloaded and placed in OPENCV_DNN_MODELS_DIR before using DNN-based tools.
• Output artifacts (images/videos) are written to disk with paths returned in tool outputs — manage file storage and cleanup according to your deployment needs.

Repository and source code: https://github.com/GongRzhe/opencv-mcp-server