imagefeatures-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@imagefeatures-mcp check blurriness in photo.jpg"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
imagefeatures-mcp 🖼️
Give LLMs "mathematical eyes" for image analysis.
An MCP (Model Context Protocol) server that wraps the imagefeatures library, exposing classic computer vision features as tools that Claude and other LLMs can use.
Why This Exists
LLM Vision | imagefeatures MCP |
"A sunset photo with warm colors" |
|
"Looks sharp to me" (often wrong) | Texture entropy: 1.2 → blur score: 0.78 |
Slow on 10,000 images | Extract once, query instantly |
LLMs see semantics ("a dog on a beach"). imagefeatures sees statistics (color histograms, texture patterns, edge orientations). Combine them for agents that reason about both content AND composition.
Related MCP server: llm-vision
What You Can Build
1. Visual Similarity Search
Find images similar by color, texture, or combined features:

Same query image returns different results based on which feature you prioritize — CEDD finds structural matches, Color Histogram finds palette matches, LBP finds texture matches.
2. Color-Based Organization
Sort images by dominant hue for color-organized galleries:

Images automatically sorted: grayscale → warm tones → greens → blues → reds
3. Vibe-Based Filtering
Filter by visual "mood" categories derived from mathematical features:

"Blue/Water" and "Green/Nature" tags computed from color + texture analysis, not AI labeling
Installation
# Install the MCP server
pip install imagefeatures-mcp
# Or install from source
pip install git+https://github.com/kelkalot/imagefeatures-mcp.gitDependencies:
imagefeatures — the underlying feature extraction library
mcp — Model Context Protocol SDK
numpy, pillow
Quick Start
Claude Desktop
Add to your Claude Desktop config:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"imagefeatures": {
"command": "python",
"args": ["-m", "imagefeatures_mcp"]
}
}
}Restart Claude Desktop. You can now ask:
"What are the dominant colors in this photo?"
"Find similar images in my ~/Photos folder"
"Sort these images by color"
"Which of these photos are blurry?"
Programmatic Usage
# Run the server directly
python -m imagefeatures_mcp
# Test with MCP Inspector
npx @modelcontextprotocol/inspector python -m imagefeatures_mcpAvailable Tools
analyze_image
Analyze an image's visual composition using mathematical features.
analyze_image(image_path, preset="quick")Presets:
Preset | Features | Dimensions | Use Case |
| ColorHistogram, EdgeHistogram | 144 | Fast overview |
| ColorHistogram, ColorMoments, DominantColors, OpponentHistogram | 605 | Color analysis |
| LBP, Tamura, Haralick, Gabor | 328 | Texture analysis |
| EdgeHistogram, HOG, HuMoments | 231 | Shape/edge analysis |
| CEDD, FCTH, JCD | 504 | Best for similarity |
| All 22 features | 3,058 | Comprehensive |
compare_images
Compare two images mathematically.
compare_images(image_a, image_b, feature="CEDD", metric="cosine")Features: Any of the 22 available (CEDD, JCD, ColorHistogram, PHOG, etc.)
Metrics: cosine, euclidean, l1, jsd, tanimoto
find_similar_in_folder
Find visually similar images in a folder.
find_similar_in_folder(query_image, folder_path, top_k=5, feature="JCD")get_dominant_colors
Extract dominant colors with exact hex codes.
get_dominant_colors(image_path, num_colors=5)check_image_quality
Detect blur and quality issues using texture analysis.
check_image_quality(image_path)sort_by_color
Sort all images in a folder by dominant hue.
sort_by_color(folder_path)filter_by_vibe
Filter images by visual category.
filter_by_vibe(folder_path, vibe="blue_water")Vibes: blue_water, green_nature, warm_sunset, cool_moody, high_contrast, soft_minimal, grayscale, vibrant
extract_features
Get raw feature vectors for ML pipelines.
extract_features(image_path, features="CEDD,PHOG,DominantColors")list_features
List all 22 available features with descriptions.
Available Features
The imagefeatures library provides 22 classic computer vision descriptors totaling 3,058 dimensions:
Color Features (741 dims)
Feature | Dims | Description |
| 64 | RGB/HSV/Luminance histogram |
| 9 | Mean, std, skewness per channel |
| 512 | Opponent color space histogram |
| 72 | Fuzzy HSV quantization |
| 20 | K-means extracted dominant colors |
| 64 | MPEG-7 Haar-based color descriptor |
Texture Features (620 dims)
Feature | Dims | Description |
| 256 | Classic LBP histogram |
| 36 | Rotation-invariant LBP |
| 48 | Multi-scale Gabor wavelets |
| 18 | Coarseness, contrast, directionality |
| 6 | GLCM texture features |
| 256 | Census transform histogram |
Shape Features (861 dims)
Feature | Dims | Description |
| 80 | MPEG-7 edge directions |
| 630 | Pyramid histogram of oriented gradients |
| 144 | Histogram of oriented gradients |
| 7 | Shape-invariant Hu moments |
Layout Features (76 dims)
Feature | Dims | Description |
| 12 | MPEG-7 DCT color layout |
| 64 | DCT luminance descriptor |
Combined Features (760 dims)
Feature | Dims | Description |
| 144 | Color + edge directivity |
| 192 | Fuzzy color + texture |
| 168 | Joint CEDD + FCTH |
| 256 | Spatial color correlation |
Recommended for Common Tasks
Task | Recommended Feature |
General similarity search |
|
Color matching |
|
Texture analysis |
|
Shape matching |
|
Duplicate detection |
|
Example Workflows
"Vibe-Based" Asset Search
User: "Find marketing images that feel calm and professional"
Claude's strategy:
1. filter_by_vibe(folder, "blue_water") → narrows to ~200 images
2. get_dominant_colors() → filters for brand palette match
3. check_image_quality() → removes blurry images
4. Uses native vision on finalists to confirm contentBrand Compliance Checker
User: "Do these product photos match our brand colors?"
Claude's strategy:
1. get_dominant_colors() on each image
2. Compare hex codes to brand palette (#1a73e8, #ffffff)
3. Report images that deviate > 10%Photo Library Deduplication
User: "Find duplicate or near-duplicate photos"
Claude's strategy:
1. extract_features() with JCD for all images
2. compare_images() pairwise
3. Group images with > 90% similarityLLM Vision vs imagefeatures
Task | LLM Vision | imagefeatures | Winner |
"What's in this image?" | ✅ Excellent | ❌ Can't do | LLM |
Exact color hex codes | ❌ Guesses | ✅ Precise | imagefeatures |
Blur detection | ❌ Often wrong | ✅ ~90% accurate | imagefeatures |
Search 10,000 images | Slow, expensive | Fast, free | imagefeatures |
"What emotion does this convey?" | ✅ Excellent | ❌ Can't do | LLM |
Consistent, reproducible | ❌ Variable | ✅ Deterministic | imagefeatures |
Best approach: Use both. imagefeatures for precision/scale, LLM vision for understanding.
Development
# Clone the repo
git clone https://github.com/kelkalot/imagefeatures-mcp.git
cd imagefeatures-mcp
# Install in development mode
pip install -e ".[dev]"
# Run tests
pytest
# Run the server locally
python -m imagefeatures_mcpRelated Projects
imagefeatures — The underlying feature extraction library
MCP — Model Context Protocol specification
LIRE — Java library that inspired imagefeatures
License
MIT
Citation
If you use this in research, please cite:
@software{imagefeatures_mcp,
title = {imagefeatures-mcp: MCP Server for Classic Image Features},
author = {Michael A. Riegler},
url = {https://github.com/kelkalot/imagefeatures-mcp},
year = {2025}
}Available Tools
9 toolsanalyze_imageA
Analyze an image's visual composition using mathematical features.
This extracts statistical properties (color distribution, texture patterns, edge orientations) that describe HOW an image looks, not WHAT it contains.
Args: image_path: Path to the image file (jpg, png, webp, etc.) preset: Analysis depth - one of: - "quick": Color histogram + edges (144 dims, fast) - "color": Detailed color analysis (605 dims) - "color_advanced": Fuzzy, scalable, correlogram features - "texture": LBP, Tamura, Haralick, Gabor (328 dims) - "texture_advanced": Rotation-invariant LBP, Centrist - "shape": Edge histogram, HOG, Hu moments (231 dims) - "shape_advanced": PHOG pyramid (630 dims) - "layout": Spatial color/luminance layout (76 dims) - "combined": CEDD, FCTH, JCD - best for similarity (504 dims) - "full": All 22 features (3058 dims, comprehensive)
Returns: Human-readable analysis with feature interpretations.
Inputs: image_path (required), preset. Returns: result
check_image_qualityA
Analyze image quality: blur, contrast, texture complexity.
Uses texture analysis to detect blur and quality issues. More reliable than asking an LLM to visually judge blur.
Args: image_path: Path to the image
Returns: Quality assessment with specific metrics.
Inputs: image_path (required). Returns: result
compare_imagesA
Compare two images mathematically to get a similarity score.
This measures visual similarity based on mathematical features, NOT semantic content. Different subjects can be "similar" if they share color palettes, textures, or compositions.
Args: image_a: Path to first image image_b: Path to second image feature: Feature for comparison. Recommended: - "CEDD": Color + edge (144 dims, good general purpose) - "JCD": Joint CEDD+FCTH (168 dims, best for similarity) - "ColorHistogram": Color only (64 dims) - "LocalBinaryPatterns": Texture only (256 dims) - "PHOG": Shape only (630 dims) metric: Distance metric - "cosine", "euclidean", "l1"
Returns: Similarity score (0-100%) and interpretation.
Inputs: image_a (required), image_b (required), feature, metric. Returns: result
extract_featuresA
Extract raw feature vectors from an image.
Returns numerical vectors for custom ML pipelines, database indexing, or advanced analysis.
Args: image_path: Path to the image features: Comma-separated feature names. Available (22 total): Color: ColorHistogram, ColorMoments, OpponentHistogram, FuzzyColorHistogram, DominantColors, ScalableColor Texture: LocalBinaryPatterns, RotationInvariantLBP, Gabor, Tamura, Haralick, Centrist Shape: EdgeHistogram, PHOG, HOG, HuMoments Layout: ColorLayout, LuminanceLayout Combined: CEDD, FCTH, JCD, AutoColorCorrelogram
Returns: JSON with feature vectors and statistics.
Inputs: image_path (required), features. Returns: result
filter_by_vibeA
Filter images by visual "vibe" categories.
Uses color and texture features to categorize images into semantic groups based on their mathematical properties.
Args: folder_path: Folder to search vibe: Category to filter by: - "blue_water": Blue dominant, water/sky scenes - "green_nature": Green dominant, nature scenes - "warm_sunset": Orange/red/yellow tones - "cool_moody": Blue/purple, low saturation - "high_contrast": Strong texture, high contrast - "soft_minimal": Low texture, smooth gradients - "grayscale": Black and white or desaturated - "vibrant": High saturation, colorful
Returns: List of matching images with confidence scores.
Inputs: folder_path (required), vibe (required). Returns: result
find_similar_in_folderA
Find visually similar images in a folder.
Scans all images and ranks them by visual similarity to the query. Similarity is based on mathematical features, not semantic content.
Args: query_image: Path to the reference image folder_path: Folder to search top_k: Number of results (1-20) feature: Feature for comparison - "JCD", "CEDD", "ColorHistogram", etc.
Returns: Ranked list of similar images with scores.
Inputs: query_image (required), folder_path (required), top_k, feature. Returns: result
get_dominant_colorsA
Extract the dominant colors from an image.
Uses K-means clustering to find the most prominent colors. Returns exact hex codes and percentages.
Args: image_path: Path to the image num_colors: Number of colors to return (1-5)
Returns: List of hex codes with percentages.
Inputs: image_path (required), num_colors. Returns: result
list_featuresA
List all available features from the imagefeatures library.
Returns documentation for all 22 feature extractors with dimensions and recommended use cases.
Inputs: no named parameters. Returns: result
sort_by_colorA
Sort all images in a folder by their dominant hue.
Returns images ordered: grayscale → warm (red/orange/yellow) → green → cool (blue/cyan) → purple → back to red.
Useful for creating color-organized galleries.
Args: folder_path: Folder containing images
Returns: Ordered list of images with dominant hue values.
Inputs: folder_path (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Each tool has a clearly distinct purpose: analysis, quality check, comparison, raw feature extraction, vibe filtering, similarity search, color extraction, feature listing, and color sorting. Even overlapping areas like comparison and similarity are differentiated by scope (two images vs. a folder).
All tool names follow a consistent snake_case verb_noun pattern (e.g., analyze_image, sort_by_color, get_dominant_colors). There are no mixed conventions or vague verbs like 'process' or 'do_thing'.
9 tools is appropriate for the domain of mathematical image feature extraction. Each tool provides a distinct operation without unnecessary duplication or missing essential functionality.
The tool set covers the full lifecycle of feature-based image analysis: single image analysis, quality assessment, pairwise comparison, raw feature extraction, vibe categorization, similarity search, color extraction, feature enumeration, and folder organization. No obvious gaps for the stated purpose.
Related MCP Connectors
MCP server for Qwen Image 3 AI image generation
MCP server providing access to the Scorecard API to evaluate and optimize LLM systems.
OCR, transcription, file extraction, and image generation for AI agents via MCP.
Hosted MCP server for AI photo editing: nothing to install, no desktop photo editor needed.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceMCP server that enables LLMs to understand images without native vision by converting image regions into text encodings (ASCII art, grayscale grids, color stats) and supporting progressive zoom, OCR, and overview summaries. Users can load images, get chunk overviews, crop and encode specific regions, and extract text using normalized coordinates.-
- FlicenseNot gradedqualityDmaintenanceMCP server that provides a 'borrowed eye' for text-only LLMs, enabling them to identify and describe local images via the Qwen VL vision model, including face recognition, scene description, OCR, and targeted visual questioning.-
- AlicenseAqualityCmaintenanceMCP server that analyzes images, reads code and ZIP archives, and provides text context for non-vision models.37 npm2MIT
- AlicenseAqualityCmaintenanceMCP server that gives text-only AI agents the ability to understand images via vision tools, including multi-image analysis, OCR, comparison, and structured extraction. It uses providers like OpenAI, Anthropic, Gemini, and OpenRouter to return plain text descriptions.109 npmMIT