Skip to main content
Glama

imagefeatures-mcp 🖼️

MCP License

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"

#FF6B35 (45.2%), #2D3436 (30.1%) — exact hex codes

"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

Find images similar by color, texture, or combined features:

Visual Similarity Search

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:

Color Sorting

Images automatically sorted: grayscale → warm tones → greens → blues → reds

3. Vibe-Based Filtering

Filter by visual "mood" categories derived from mathematical features:

Vibe Filtering

"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.git

Dependencies:

  • 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_mcp

Available Tools

analyze_image

Analyze an image's visual composition using mathematical features.

analyze_image(image_path, preset="quick")

Presets:

Preset

Features

Dimensions

Use Case

quick

ColorHistogram, EdgeHistogram

144

Fast overview

color

ColorHistogram, ColorMoments, DominantColors, OpponentHistogram

605

Color analysis

texture

LBP, Tamura, Haralick, Gabor

328

Texture analysis

shape

EdgeHistogram, HOG, HuMoments

231

Shape/edge analysis

combined

CEDD, FCTH, JCD

504

Best for similarity

full

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

ColorHistogram

64

RGB/HSV/Luminance histogram

ColorMoments

9

Mean, std, skewness per channel

OpponentHistogram

512

Opponent color space histogram

FuzzyColorHistogram

72

Fuzzy HSV quantization

DominantColors

20

K-means extracted dominant colors

ScalableColor

64

MPEG-7 Haar-based color descriptor

Texture Features (620 dims)

Feature

Dims

Description

LocalBinaryPatterns

256

Classic LBP histogram

RotationInvariantLBP

36

Rotation-invariant LBP

Gabor

48

Multi-scale Gabor wavelets

Tamura

18

Coarseness, contrast, directionality

Haralick

6

GLCM texture features

Centrist

256

Census transform histogram

Shape Features (861 dims)

Feature

Dims

Description

EdgeHistogram

80

MPEG-7 edge directions

PHOG

630

Pyramid histogram of oriented gradients

HOG

144

Histogram of oriented gradients

HuMoments

7

Shape-invariant Hu moments

Layout Features (76 dims)

Feature

Dims

Description

ColorLayout

12

MPEG-7 DCT color layout

LuminanceLayout

64

DCT luminance descriptor

Combined Features (760 dims)

Feature

Dims

Description

CEDD

144

Color + edge directivity

FCTH

192

Fuzzy color + texture

JCD

168

Joint CEDD + FCTH

AutoColorCorrelogram

256

Spatial color correlation

Task

Recommended Feature

General similarity search

JCD or CEDD

Color matching

DominantColors + ColorHistogram

Texture analysis

Gabor + Tamura

Shape matching

PHOG or HuMoments

Duplicate detection

JCD (fast, effective)

Example Workflows

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 content

Brand 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% similarity

LLM 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_mcp
  • 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 tools
analyze_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

    A4.2/5.0

    Scored across 9 tools

    Disambiguation5/5

    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).

    Naming Consistency5/5

    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'.

    Tool Count5/5

    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.

    Completeness5/5

    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

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      MCP 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.
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      MCP 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.
      -
    • A
      license
      A
      quality
      C
      maintenance
      MCP 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.
      10
      9 npm
      MIT