Skip to content
Back to search

opencv-mcp-server

OpenCV MCP Server provides OpenCV's image and video processing capabilities through the Model Context Protocol (MCP). Access powerful computer vision tools for tasks ranging from basic image manipulation to advanced object detection and tracking.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/gongrzhe--opencv-mcp-server/badge.svg)](/listings/gongrzhe--opencv-mcp-server)

HTML

<a href="/listings/gongrzhe--opencv-mcp-server"><img src="/api/listings/gongrzhe--opencv-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

pip install opencv-mcp-server

For development:

# Clone the repository
git clone https://github.com/yourusername/opencv-mcp-server.git
cd opencv-mcp-server

# Create a virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -e .

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 427 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ![logo](https://github.com/user-attachments/assets/2d4527f4-6e2a-48be-8dfe-7b40231aa212)
  2. # 🚀 OpenCV MCP Server
  3. MCP server providing powerful OpenCV computer vision capabilities for AI assistants.
  4. ![](https://badge.mcpx.dev?type=server 'MCP Server')
  5. ## 🔍 Introduction
  6. OpenCV MCP Server is a Python package that provides OpenCV's image and video processing capabilities through the Model Context Protocol (MCP). This allows AI assistants and language models to access powerful computer vision tools for tasks ranging from basic image manipulation to advanced object detection and tracking.
  7. With OpenCV MCP Server, AI systems can:
  8. - Process and analyze images in various formats
  9. - Perform real-time object detection and tracking
  10. - Extract meaningful information from visual data
  11. - Enhance and transform images using advanced algorithms
  12. - Process video content with frame-by-frame analysis
  13. ## ✨ Features
  14. - 📸 **Basic image handling and manipulation** (read, save, convert)
  15. - 🖼️ **Image processing and enhancement** (resize, crop, filter application)
  16. - 📊 **Edge detection and contour analysis**
  17. - 🧠 **Advanced computer vision capabilities** (feature detection, object detection)
  18. - 😃 **Face detection and recognition**
  19. - 🎬 **Video processing and analysis** (frame extraction, motion detection)
  20. - 🔍 **Object tracking in videos**
  21. - 📹 **Camera integration for real-time object detection**
  22. ## 📊 Demo Examples
  23. ### Edge Detection
  24. ![Edge Detection](public/DetectEdge.png)
  25. ### Face Detection
  26. ![Face Detection](public/DetectFace.png)
  27. ### Statistical Analysis
  28. ![Statistical Information](public/GetStatisticalInformation.png)
  29. ### Video Processing
  30. ![Video Processing](public/VideoProcess.png)
  31. ### Original Video Sample
  32. ![Original Video Demo](public/DemoVideo.gif)
  33. ### Contour Detection Processing
  34. ![Contour Detection](public/DemoVideoContourDetection.gif)
  35. *Example of contour detection processing applied to the original video above*
  36. ## 📦 Installation
  37. ```bash
  38. pip install opencv-mcp-server
  39. ```
  40. For development:
  41. ```bash
  42. # Clone the repository
  43. git clone https://github.com/yourusername/opencv-mcp-server.git
  44. cd opencv-mcp-server
  45. # Create a virtual environment
  46. python -m venv .venv
  47. source .venv/bin/activate # On Windows: .venv\Scripts\activate
  48. # Install dependencies
  49. pip install -e .
  50. ```
  51. ## 🔧 Usage
  52. ### Use in Claude Desktop
  53. Add to your Claude Desktop configuration:
  54. ```json
  55. {
  56. "mcpServers": {
  57. "opencv": {
  58. "command": "uvx",
  59. "args": [
  60. "opencv-mcp-server"
  61. ]
  62. }
  63. }
  64. }
  65. ```
  66. Install uvx
  67. ```bash
  68. brew install uv
  69. ```
  70. Then restart Claude Desktop
  71. <img width="1026" height="749" alt="image" src="https://github.com/user-attachments/assets/0355c5a0-92ea-4f5e-a299-4ee8ed9bccd2" />
  72. ### Basic Python Usage
  73. ```python
  74. from opencv_mcp_server import opencv_client
  75. # Initialize client
  76. client = opencv_client.OpenCVClient()
  77. # Use tools
  78. result = client.resize_image(
  79. image_path="input.jpg",
  80. width=800,
  81. height=600
  82. )
  83. ```
  84. ### Advanced Object Detection Example
  85. Since all required models are already configured in the `OPENCV_DNN_MODELS_DIR`, you can use object detection without specifying model paths:
  86. ```python
  87. # Detect objects using pre-configured YOLO model
  88. result = detect_objects_tool(
  89. image_path="street.jpg",
  90. confidence_threshold=0.5,
  91. nms_threshold=0.4
  92. )
  93. ```
  94. ### Configuration
  95. The server can be configured using environment variables:
  96. - `MCP_TRANSPORT`: Transport method (default: "stdio")
  97. - `OPENCV_DNN_MODELS_DIR`: Directory for storing DNN models (default: "models")
  98. - `CV_HAAR_CASCADE_DIR`: Directory for storing Haar cascade files (optional)
  99. ## 🧠 Model Files Setup
  100. The computer vision and object detection tools require pre-trained models to function properly. These models should be placed in the directory specified by the `OPENCV_DNN_MODELS_DIR` environment variable (default: "./models").
  101. ### Required Models
  102. The following models have been pre-configured:
  103. - **Face Detection (DNN method)**
  104. - `deploy.prototxt` - Face detection configuration
  105. - `res10_300x300_ssd_iter_140000.caffemodel` - Face detection model weights
  106. - **Object Detection (YOLO)**
  107. - `yolov3.weights` - YOLO model weights
  108. - `yolov3.cfg` - YOLO configuration file
  109. - `coco.names` - Class names for detected objects
  110. ### Model Usage
  111. - The `detect_faces_tool` uses the DNN models when `method="dnn"` is specified
  112. - The `detect_objects_tool` uses the YOLO models for general object detection
  113. For those who need to download these models, see the "Installation" section or visit:
  114. - YOLO models: https://pjreddie.com/darknet/yolo/
  115. - Face detection models: https://github.com/opencv/opencv_3rdparty/tree/dnn_samples_face_detector_20170830
  116. ## 🧰 Available Tools
  117. The OpenCV MCP Server provides a wide range of computer vision tools organized into four categories:
  118. ### 📸 Image Basics
  119. These tools provide fundamental image manipulation capabilities:
  120. - `save_image_tool`: Save an image to a file
  121. - Parameters: `path_in` (input image path), `path_out` (output file path)
  122. - Returns: Image save status and path information
  123. - Example: `save_image_tool(path_in="processed.jpg", path_out="final.jpg")`
  124. - `convert_color_space_tool`: Convert image between color spaces (BGR, RGB, GRAY, HSV, etc.)
  125. - Parameters: `image_path`, `source_space`, `target_space`
  126. - Returns: Converted image information and path
  127. - Example: `convert_color_space_tool(image_path="image.jpg", source_space="BGR", target_space="HSV")`
  128. - `resize_image_tool`: Resize an image to specific dimensions
  129. - Parameters: `image_path`, `width`, `height`, `interpolation` (optional)
  130. - Returns: Resized image information and path
  131. - Example: `resize_image_tool(image_path="large.jpg", width=800, height=600)`
  132. - `crop_image_tool`: Crop a region from an image
  133. - Parameters: `image_path`, `x`, `y`, `width`, `height`
  134. - Returns: Cropped image information and path
  135. - Example: `crop_image_tool(image_path="scene.jpg", x=100, y=150, width=300, height=200)`
  136. - `get_image_stats_tool`: Get statistical information about an image
  137. - Parameters: `image_path`, `channels` (boolean, default: true)
  138. - Returns: Image statistics and histogram visualization
  139. - Example: `get_image_stats_tool(image_path="photo.jpg", channels=True)`
  140. ### 🖼️ Image Processing
  141. These tools provide advanced image processing and transformation capabilities:
  142. - `apply_filter_tool`: Apply various filters to an image (blur, gaussian, median, bilateral)
  143. - Parameters: `image_path`, `filter_type`, `kernel_size`, and filter-specific parameters
  144. - Returns: Filtered image and filter information
  145. - Example: `apply_filter_tool(image_path="noisy.jpg", filter_type="gaussian", kernel_size=5)`
  146. - `detect_edges_tool`: Detect edges in an image using different methods (Canny, Sobel, Laplacian, Scharr)
  147. - Parameters: `image_path`, `method`, threshold parameters, and method-specific parameters
  148. - Returns: Edge-detected image and method information
  149. - Example: `detect_edges_tool(image_path="objects.jpg", method="canny", threshold1=100, threshold2=200)`
  150. - `apply_threshold_tool`: Apply threshold to an image (binary, adaptive, etc.)
  151. - Parameters: `image_path`, `threshold_type`, threshold values and method-specific parameters
  152. - Returns: Thresholded image and threshold information
  153. - Example: `apply_threshold_tool(image_path="scan.jpg", threshold_type="binary", threshold_value=127)`
  154. - `detect_contours_tool`: Detect and optionally draw contours in an image
  155. - Parameters: `image_path`, `mode`, `method`, drawing parameters
  156. - Returns: Image with contours and contour information
  157. - Example: `detect_contours_tool(image_path="shapes.jpg", mode="external", method="simple")`
  158. - `find_shapes_tool`: Find basic shapes in an image (circles, lines)
  159. - Parameters: `image_path`, `shape_type`, shape-specific parameters
  160. - Returns: Image with shapes and shape information
  161. - Example: `find_shapes_tool(image_path="geometry.jpg", shape_type="circles", min_radius=10)`
  162. - `match_template_tool`: Find a template in an image
  163. - Parameters: `image_path`, `template_path`, matching parameters
  164. - Returns: Image with matches and match information
  165. - Example: `match_template_tool(image_path="scene.jpg", template_path="object.jpg", threshold=0.8)`
  166. ### 🧠 Computer Vision
  167. These tools provide high-level computer vision capabilities:
  168. - `detect_features_tool`: Detect features in an image using methods like SIFT, ORB, BRISK
  169. - Parameters: `image_path`, `method`, `max_features`, drawing parameters
  170. - Returns: Image with keypoints and feature information
  171. - Example: `detect_features_tool(image_path="landmark.jpg", method="sift", max_features=500)`
  172. - `match_features_tool`: Match features between two images
  173. - Parameters: `image1_path`, `image2_path`, `method`, matching parameters
  174. - Returns: Image with matches and match information
  175. - Example: `match_features_tool(image1_path="scene1.jpg", image2_path="scene2.jpg", method="sift")`
  176. - `detect_faces_tool`: Detect faces in an image using Haar cascades or DNN
  177. - Parameters: `image_path`, `method`, method-specific parameters
  178. - Returns: Image with faces and face information
  179. - Example: `detect_faces_tool(image_path="group.jpg", method="haar", min_neighbors=5)`
  180. - `detect_objects_tool`: Detect objects using pre-trained DNN models (e.g., YOLO)
  181. - Parameters: `image_path`, model paths, detection parameters
  182. - Returns: Image with objects and object information
  183. - Example: `detect_objects_tool(image_path="street.jpg", confidence_threshold=0.5)`
  184. ### 🎬 Video Processing
  185. These tools provide video analysis and processing capabilities:
  186. - `extract_video_frames_tool`: Extract frames from a video file
  187. - Parameters: `video_path`, frame selection parameters
  188. - Returns: Extracted frames information and paths
  189. - Example: `extract_video_frames_tool(video_path="clip.mp4", start_frame=0, step=10, max_frames=20)`
  190. - `detect_motion_tool`: Detect motion between two frames
  191. - Parameters: `frame1_path`, `frame2_path`, detection parameters
  192. - Returns: Motion detection results and visualizations
  193. - Example: `detect_motion_tool(frame1_path="frame1.jpg", frame2_path="frame2.jpg", threshold=25)`
  194. - `track_object_tool`: Track an object across video frames
  195. - Parameters: `video_path`, `initial_bbox`, tracking parameters
  196. - Returns: Tracking results and extracted frames
  197. - Example: `track_object_tool(video_path="tracking.mp4", initial_bbox=[100, 100, 50, 50])`
  198. - `combine_frames_to_video_tool`: Combine frames into a video file
  199. - Parameters: `frame_paths`, `output_path`, video parameters
  200. - Returns: Video creation results
  201. - Example: `combine_frames_to_video_tool(frame_paths=["frame1.jpg", "frame2.jpg"], output_path="output.mp4")`
  202. - `create_mp4_from_video_tool`: Convert a video file to MP4 format
  203. - Parameters: `video_path`, `output_path`, conversion parameters
  204. - Returns: Conversion results including MP4 path
  205. - Example: `create_mp4_from_video_tool(video_path="input.avi", output_path="output.mp4")`
  206. - `detect_video_objects_tool`: Detect objects in a video and create a detection result video
  207. - Parameters: `video_path`, model paths, detection parameters
  208. - Returns: Object detection results and output video path
  209. - Example: `detect_video_objects_tool(video_path="traffic.mp4", confidence_threshold=0.5)`
  210. - `detect_camera_objects_tool`: Detect objects from computer's camera and save to video
  211. - Parameters: `camera_id`, recording parameters, model paths, detection parameters
  212. - Returns: Object detection results and output video path
  213. - Example: `detect_camera_objects_tool(camera_id=0, duration=30, confidence_threshold=0.5)`
  214. ## 📝 Advanced Usage Examples
  215. ### 📸 Basic Image Processing
  216. ```python
  217. # Resize an image
  218. result = resize_image_tool(
  219. image_path="input.jpg",
  220. width=800,
  221. height=600
  222. )
  223. # Access the resized image path
  224. resized_image_path = result["output_path"]
  225. # Apply a Gaussian blur filter
  226. result = apply_filter_tool(
  227. image_path="input.jpg",
  228. filter_type="gaussian",
  229. kernel_size=5,
  230. sigma=1.5
  231. )
  232. ```
  233. ### 🧠 Object Detection
  234. ```python
  235. # Detect objects in an image using YOLO
  236. result = detect_objects_tool(
  237. image_path="scene.jpg",
  238. confidence_threshold=0.5,
  239. nms_threshold=0.4
  240. )
  241. # Access detected objects
  242. objects = result["objects"]
  243. for obj in objects:
  244. print(f"Detected {obj['class_name']} with confidence {obj['confidence']}")
  245. ```
  246. ### 🎬 Video Analysis
  247. ```python
  248. # Extract frames from a video
  249. result = extract_video_frames_tool(
  250. video_path="input.mp4",
  251. start_frame=0,
  252. step=10,
  253. max_frames=10
  254. )
  255. # Access extracted frames
  256. frames = result["frames"]
  257. # Detect objects in a video
  258. result = detect_video_objects_tool(
  259. video_path="input.mp4",
  260. confidence_threshold=0.5,
  261. frame_step=5
  262. )
  263. ```
  264. ### 🔄 Chaining Operations
  265. Tools can be chained together by using the `output_path` from one tool as the input to another:
  266. ```python
  267. # First resize an image
  268. result1 = resize_image_tool(
  269. image_path="input.jpg",
  270. width=800,
  271. height=600
  272. )
  273. # Then apply edge detection to the resized image
  274. result2 = detect_edges_tool(
  275. image_path=result1["output_path"],
  276. method="canny",
  277. threshold1=100,
  278. threshold2=200
  279. )
  280. # Finally detect contours in the edge-detected image
  281. result3 = detect_contours_tool(
  282. image_path=result2["output_path"],
  283. mode="external",
  284. method="simple"
  285. )
  286. ```
  287. ## 🔍 Real-world Applications
  288. OpenCV MCP Server can be used for a wide range of applications:
  289. - 🤖 **Autonomous Systems**: Vision-based navigation and obstacle detection
  290. - 🚗 **Traffic Analysis**: Vehicle counting, speed estimation, and license plate recognition
  291. - 🔐 **Security Systems**: Motion detection and facial recognition
  292. - 📱 **Augmented Reality**: Feature tracking and pose estimation
  293. - 🏥 **Medical Imaging**: Tissue segmentation and anomaly detection
  294. - 🏭 **Industrial Inspection**: Defect detection and quality control
  295. - 🖼️ **Digital Art**: Image filtering and transformation
  296. - 🎲 **Gaming**: Gesture recognition and player tracking
  297. ## 🗺️ Roadmap
  298. Future enhancements planned for OpenCV MCP Server:
  299. - 📊 Additional statistical analysis tools
  300. - 🧬 Advanced segmentation algorithms
  301. - 🧠 Integration with machine learning models
  302. - 🌐 3D vision capabilities
  303. - 📱 Mobile-friendly processing options
  304. - ⚡ Performance optimizations for real-time processing
  305. ## 🤝 Contributing
  306. Contributions are welcome! Please feel free to submit a Pull Request.
  307. 1. Fork the project
  308. 2. Create your feature branch (`git checkout -b feature/amazing-feature`)
  309. 3. Commit your changes (`git commit -m 'Add some amazing feature'`)
  310. 4. Push to the branch (`git push origin feature/amazing-feature`)
  311. 5. Open a Pull Request
  312. ## 📜 License
  313. MIT License - See the LICENSE file for details.
  314. ## 📞 Contact
  315. For questions or feedback, please open an issue on the GitHub repository.
  316. ---
  317. Built with ❤️ using OpenCV and Python.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.