OpticMCP Server

OpticMCP is a portable MCP server that exposes a versatile set of camera and vision tools for AI assistants. It lets you connect to USB or network cameras, capture images, stream video, analyze scenes, decode codes, and perform image comparisons and detections all from a single endpoint you can integrate with your MCP clients.

How to use

You interact with the OpticMCP server through MCP clients. Start the server locally, then connect any compatible client to the running MCP server to access its camera streams, image tools, and analysis features. The server provides both local (stdio) execution methods and options to run via an MCP URL when available.

How to install

Prerequisites: install Python 3.10 or newer on your system.

Install from PyPI (recommended):

pip install optic-mcp

Alternative using uvx (no global installation required):

uv pip install optic-mcp

Install from source: clone the repository, then install dependencies using uv, and run from source.

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

# Install dependencies with uv
uv sync

Additional sections

MCP server configuration and how to run the server with different clients are shown here as concrete examples. Use the commands and JSON blocks exactly as shown to connect clients to the optic-mcp server.

Running the MCP server from the installed package or from source is described in the following sections.

Tools

The server exposes a wide set of tools organized by capability. Each tool is described below to help you plan how to compose MCP client requests.

Tool list and descriptions

• list_cameras: Scans for available USB cameras and returns their status, including index and backend information.

• save_image: Captures a frame from a camera and saves it to disk. Parameters include the file_path and the camera_index.

Streaming and dashboard tools

• start_stream: Start streaming a camera to a local HTTP server using MJPEG so you can view it in a browser.

• stop_stream: Stop an active camera stream.

• list_streams: List all active camera streams and their access URLs.

• start_dashboard: Launch a dynamic dashboard that displays all active streams in a responsive grid.

• stop_dashboard: Stop the dashboard server.

RTSP, HLS, and MJPEG tools

• rtsp_save_image: Capture a frame from an RTSP stream and save it to disk.

• rtsp_check_stream: Validate an RTSP stream and report properties such as width, height, fps, and codec.

• hls_save_image: Capture a frame from an HLS stream and save it to disk.

• hls_check_stream: Validate an HLS stream and report properties.

• mjpeg_save_image: Capture a frame from an MJPEG stream and save it to disk.

• mjpeg_check_stream: Validate an MJPEG stream URL.

Screen capture and HTTP image tools

• screen_list_monitors: List all available monitors.

• screen_save_image: Capture a full screenshot of a monitor.

• screen_save_region: Capture a specific region of the screen.

• http_save_image: Download an image from a URL and save it to disk.

• http_check_image: Check if a URL points to a valid image.

QR and barcode decoding

• decode_qr: Decode QR codes from an image. Requires the libzbar library.

• decode_barcode: Decode barcodes from an image.

• decode_all: Decode all codes from an image.

• decode_and_annotate: Decode codes and save an annotated image with bounding boxes.

Image analysis tools

• image_get_metadata: Extract image metadata including dimensions, format, and EXIF data.

• image_get_stats: Calculate brightness, contrast, and sharpness.

• image_get_histogram: Generate a color histogram with optional visualization.

• image_get_dominant_colors: Extract dominant colors using K-means clustering.

Image comparison tools

• image_compare_ssim: Compare two images using Structural Similarity Index.

• image_compare_mse: Compare two images using Mean Squared Error.

• image_compare_hash: Compare two images using perceptual hashing (phash, dhash, ahash).

• image_get_hash: Generate a perceptual hash for an image.

• image_diff: Create a visual diff highlighting differences between two images.

• image_compare_histograms: Compare images by color histograms.

Detection tools

• detect_faces: Detect faces using Haar cascades or DNN.

• detect_faces_save: Detect faces and save an annotated image.

• detect_motion: Detect motion between two frames.

• detect_edges: Detect edges using canny, sobel, or laplacian.

• detect_objects: Detect common objects using MobileNet SSD.

Technical notes and roadmap

OpenCV compatibility is handled to suppress debug noise in stdio communication. The project has a structured roadmap that tracks USB camera support, IP cameras, dashboards, screen capture, analysis tools, and detection capabilities.

Available tools

list_cameras

Scans for available USB cameras (indices 0-9) and returns their status.

save_image

Captures a frame from a camera and saves it to disk. Includes camera_index and file_path parameters.

start_stream

Start streaming a camera to a localhost HTTP server using MJPEG for browser viewing.

stop_stream

Stop an active camera stream.

list_streams

List all active camera streams with their access URLs.

start_dashboard

Launch a dynamic multi-camera dashboard showing all active streams in a responsive grid.

stop_dashboard

Stop the multi-camera dashboard server.

rtsp_save_image

Capture a frame from an RTSP stream and save it to disk.

rtsp_check_stream

Validate an RTSP stream and report its properties.

hls_save_image

Capture a frame from an HLS stream and save it to disk.

hls_check_stream

Validate an HLS stream and report its properties.

mjpeg_save_image

Capture a frame from an MJPEG stream and save it to disk.

mjpeg_check_stream

Validate an MJPEG stream URL.

screen_list_monitors

List all available monitors.

screen_save_image

Capture a full screenshot of a monitor.

screen_save_region

Capture a specific region of the screen.

http_save_image

Download an image from a URL and save it to disk.

http_check_image

Check if a URL points to a valid image.

decode_qr

Decode QR codes from an image. Requires libzbar.

decode_barcode

Decode barcodes from an image.

decode_all

Decode all QR codes and barcodes from an image.

decode_and_annotate

Decode codes and save an annotated image with bounding boxes.

image_get_metadata

Extract metadata from an image file including dimensions, format, and EXIF data.

image_get_stats

Calculate brightness, contrast, and sharpness of an image.

image_get_histogram

Generate a color histogram with optional visualization.

image_get_dominant_colors

Extract dominant colors using K-means clustering.

image_compare_ssim

Compare two images using Structural Similarity Index.

image_compare_mse

Compare two images using Mean Squared Error.

image_compare_hash

Compare two images using perceptual hashing (phash, dhash, ahash).

image_get_hash

Generate a perceptual hash for an image.

image_diff

Create a visual diff highlighting differences between two images.

image_compare_histograms

Compare images by color histograms.

detect_faces

Detect faces in an image using Haar cascades or DNN.

detect_faces_save

Detect faces and save an annotated image.

detect_motion

Detect motion between two frames.

detect_edges

Detect edges using canny, sobel, or laplacian.

detect_objects

Detect common objects using MobileNet SSD.