# imagefeatures-mcp 🖼️

[![MCP](https://img.shields.io/badge/MCP-Compatible-blue)](https://modelcontextprotocol.io)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

**Give LLMs "mathematical eyes" for image analysis.**

An MCP (Model Context Protocol) server that wraps the [imagefeatures](https://github.com/kelkalot/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.

## What You Can Build

### 1. Visual Similarity Search

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

![Visual Similarity Search](docs/images/similarity_search.png)

*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](docs/images/color_sorting.png)

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

### 3. Vibe-Based Filtering

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

![Vibe Filtering](docs/images/vibe_filtering.png)

*"Blue/Water" and "Green/Nature" tags computed from color + texture analysis, not AI labeling*

## Installation

```bash
# Install the MCP server
pip install imagefeatures-mcp

# Or install from source
pip install git+https://github.com/kelkalot/imagefeatures-mcp.git
```

**Dependencies:**
- [imagefeatures](https://github.com/kelkalot/imagefeatures) — the underlying feature extraction library
- [mcp](https://pypi.org/project/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`

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

```bash
# 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](https://github.com/kelkalot/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 |

### Recommended for Common Tasks

| 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

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

| 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

```bash
# 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](https://github.com/kelkalot/imagefeatures)** — The underlying feature extraction library
- **[MCP](https://modelcontextprotocol.io)** — Model Context Protocol specification
- **[LIRE](https://github.com/dermotte/lire)** — Java library that inspired imagefeatures

## License

MIT

## Citation

If you use this in research, please cite:

```bibtex
@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}
}
```