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

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.

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

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)

Texture Features (620 dims)

Shape Features (861 dims)

Layout Features (76 dims)

Combined Features (760 dims)

Recommended for Common Tasks

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

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

Related 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}
}