farshid-mcp-imageProcessing

farshid-mcp-imageProcessing

A comprehensive OpenCV image-processing MCP server for VS Code Copilot Agent Mode (or any MCP client). Exposes ~40 tools across webcam capture, image I/O, transforms, color, filtering, edges, thresholding, morphology, contours/shapes, feature matching, object detection (faces / eyes / bodies / QR), drawing, image arithmetic, template matching, and video processing.

• PyPI: farshid-mcp-imageProcessing
• MCP Registry: io.github.pirahansiah/farshid-mcp-imageProcessing
• Python: 3.14+
• OS: latest Windows 11, latest macOS, latest mainstream Linux (Ubuntu 24.04+/Fedora 41+)

Install (PyPI)

pip install farshid-mcp-imageProcessing
farshid-mcp-imageprocessing          # runs the stdio MCP server

Register in VS Code

Add this to your user or workspace mcp.json:

{
  "servers": {
    "imageProcessing": {
      "command": "farshid-mcp-imageprocessing",
      "type": "stdio"
    }
  }
}

Or, if you cloned the repo and want to run from source with the local .venv:

git clone https://github.com/pirahansiah/farshid-mcp-imageProcessing
cd farshid-mcp-imageProcessing
# Windows (PowerShell):
py -3.14 -m venv .venv ; .\.venv\Scripts\Activate.ps1
# macOS / Linux:
python3.14 -m venv .venv && source .venv/bin/activate

pip install -U pip
pip install -e .

opencv-contrib-python is used so the bundled Haar cascades and extra algorithms are available.

Quick start: the /cv Copilot prompt

This repo ships a workspace prompt file at .github/prompts/cv.prompt.md. In VS Code Copilot Chat (Agent mode), type:

/cv take image from webcam and save it as gray scale 240 * 240

The agent will call webcam_save, image_to_grayscale, and image_resize from this server to produce the requested file under ./.farshid/cv/.

Tool catalog

Webcam / capture

• webcam_capture(camera_index=0) → returns a PNG image
• webcam_save(output_path="", camera_index=0)
• webcam_preview(camera_index=0, seconds=10) (local desktop window)
• webcam_record(output_path, seconds=5, camera_index=0, fps=20)

Image I/O & info

• image_show(path) — return image to chat
• image_info(path) — shape, dtype, mean, file size
• image_convert(input_path, output_path, quality=95)

Geometric transforms

• image_resize(... width|height|scale, interpolation)
• image_crop(input_path, output_path, x, y, width, height)
• image_rotate(input_path, output_path, angle, scale=1, keep_size=False)
• image_flip(input_path, output_path, direction)
• image_pad(... top, bottom, left, right, border_type, color)

Color

• image_to_grayscale
• color_convert(target=gray|hsv|hls|lab|ycrcb|rgb|bgr)
• adjust_brightness_contrast
• histogram_equalize(method=clahe|global)
• histogram_data(bins=32)

Filtering

• blur_gaussian(ksize, sigma)
• blur_median(ksize)
• blur_bilateral(d, sigma_color, sigma_space)
• sharpen(amount)
• denoise(strength)

Edges / gradients

• edges_canny(threshold1, threshold2)
• edges_sobel(ksize)
• edges_laplacian(ksize)

Thresholding & morphology

• threshold(method=otsu|binary|binary_inv|adaptive_mean|adaptive_gaussian)
• morphology(op=erode|dilate|open|close|gradient|tophat|blackhat)

Contours & shapes

• find_contours(input_path, output_path?, thresh, min_area)
• detect_circles(...) — Hough
• detect_lines(...) — Probabilistic Hough
• detect_corners(...) — Shi-Tomasi

Feature matching

• feature_match(image1, image2, output_path?) — ORB + BFMatcher

Object detection (Haar)

• detect_faces
• detect_eyes
• detect_bodies
• detect_qrcode

Drawing

• draw_rectangle, draw_circle, draw_line, draw_text

Composition / arithmetic

• image_blend(image1, image2, output_path, alpha)
• image_diff(image1, image2, output_path?) → mean/max diff
• image_concat(images, output_path, direction)
• template_match(image_path, template_path, output_path?, threshold)

Video

• video_info(path)
• video_extract_frames(video_path, output_dir, every_n, max_frames, ext)
• video_thumbnail(video_path, output_path, time_seconds)

Build & publish

pip install -U build twine mcp-publisher
python -m build
twine upload dist/*
mcp-publisher login github
mcp-publisher publish .mcp/server.json

OS notes

• Windows 11 (latest): webcam works out of the box; ensure Settings → Privacy & security → Camera → Let desktop apps access your camera is On.
• macOS (latest): the first webcam call triggers a system Camera permission prompt; grant it to the terminal/VS Code process.
• Linux (latest): requires a working /dev/video* device. Headless servers without a display cannot use webcam_preview (it opens an OpenCV window).

Notes

• Never use print() in tool functions: stdout is the MCP protocol channel. Use sys.stderr (the _log helper at the bottom of server.py).
• webcam_preview opens a real desktop window — only works where the server has a display (not over plain SSH or in a headless container).
• All paths support ~ expansion. Output directories are created automatically.
• Tools that return annotated images take an optional output_path; when omitted they only return the JSON metadata.