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., "@local-image-search find pictures of a sunset"
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.
Give your AI coding agent the ability to search through all your local images. Privacy-first, 100% local MCP server for macOS. Uses MLX CLIP for embeddings, Daft for batch processing, and Lance for vector storage.
https://github.com/user-attachments/assets/41e167f0-bb73-4310-8c1c-4be07af21cc1
100% local - Images and embeddings never leave your machine
MCP Server - Works with Claude Code and Claude Desktop
Natural language search - Find images by describing them
Fast - 260+ images/second on Apple Silicon via MLX
Related MCP server: ContextCore
macOS with Apple Silicon (M1/M2/M3/M4)
uv (for uvx command)
Option 1: CLI
claude mcp add local-image-search -- uvx local-image-searchOption 2: Manual - add to ~/.claude.json:
{
"mcpServers": {
"local-image-search": {
"command": "uvx",
"args": ["local-image-search"]
}
}
}Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"local-image-search": {
"command": "uvx",
"args": ["local-image-search"]
}
}
}Restart Claude after setup. The first run downloads the model (~600MB) and embeds your images, which may take a few minutes. After that, it only processes new or changed files. By default, it scans your home directory (~) and skips common system folders. See Configuration Logic for details.
Scan a specific folder:
{
"args": ["local-image-search", "~/Pictures"]
}Custom excludes:
{
"args": ["local-image-search"],
"env": {
"EXCLUDE_DIRS": "Downloads,Desktop,Movies"
}
}Faster refresh:
{
"env": {
"REFRESH_INTERVAL": "30"
}
}Options | Root | Excludes |
None |
| Default excludes |
Root only | Custom root | None |
Excludes only |
| Custom excludes |
Root + Excludes | Custom root | Custom excludes |
Default excludes: Library, .Trash, .cache, Cache, node_modules, .git, .venv, venv
search_images(query, limit) - Search for images matching a text description
get_status() - Check if the service is ready (model loaded, embeddings synced)
# Clone the repo
git clone https://github.com/Eventual-Inc/local-image-search.git
cd local-image-search
# Install dependencies
uv sync
# Download and convert CLIP model (~600MB, first time only)
cd clip && uv run python convert.py && cd ..uv run python embed.py ~/Pictures # embed all images
uv run python embed.py ~/Pictures --dry-run # count and estimate time
uv run python embed.py . --no-recursive # current dir onlyEmbeddings are cached in embeddings.lance/. Re-running skips unchanged files.
Format | Extensions | Tested |
JPEG |
| Created and embedded |
PNG |
| Created and embedded |
GIF |
| Created and embedded |
WebP |
| Created and embedded |
BMP |
| Created and embedded |
TIFF |
| Created and embedded |
HEIC/HEIF |
| Real iPhone photo + converted PNG |
Corrupted or unreadable images get zero vectors (won't match searches).
Start the server (loads model once):
uv run python server.pySearch via CLI:
uv run python search.py "sunset" # list results
uv run python search.py "people" -n 10 # show 10 resultsOr via API:
curl -X POST http://127.0.0.1:8000/search \
-H "Content-Type: application/json" \
-d '{"query": "yellow mouse", "limit": 5}'uv run python simple_image_search.py # basic in-memory search (2 images)
uv run python daft_image_search.py # batch processing demolocal-image-search/
├── clip/ # MLX CLIP implementation (from ml-explore/mlx-examples)
│ ├── model.py # CLIP model architecture
│ ├── clip.py # Model loading and inference
│ ├── convert.py # HuggingFace to MLX converter
│ ├── image_processor.py # Image preprocessing
│ ├── tokenizer.py # Text tokenization
│ ├── mlx_model/ # Converted model weights (generated)
│ └── LICENSE # MIT License (Apple Inc.)
├── data/
│ └── pokemon/ # Pokemon artwork (1025 images)
├── embeddings.lance/ # Lance DB storage (generated)
├── mcp_server.py # MCP server entry point
├── server.py # FastAPI server for local API
├── search.py # CLI search tool
├── core.py # Shared utilities (EmbedImages, find_images, etc.)
├── embed.py # CLI tool to sync embeddings from a directory
├── test_embed.py # Tests for embed.py
├── simple_image_search.py # Basic in-memory search demo
├── daft_image_search.py # Daft-based batch processing demo
├── benchmark.py # Benchmark script
├── plot_benchmark.py # Generate benchmark plot
├── benchmark_results.csv # Raw benchmark data (10 runs)
├── benchmark_plot.png # Benchmark visualization
├── pyproject.toml # Project dependencies
└── uv.lock # Dependency lockfileEmbedding time for the Pokemon dataset (1025 images) on M4 Max, averaged over 10 runs.
Run benchmarks yourself:
uv run python benchmark.py # Run one iteration, appends to CSV
uv run python benchmark.py 100 # Benchmark with specific number of images
uv run python plot_benchmark.py # Generate plot from CSVMetric | Value |
Images found | 11,843 |
Scan time | ~26s |
Embed time | ~39s |
Total time | ~65s |
Embed speed | 260 img/s |
Re-run (cached) | ~31s (scan only) |
Source: PokeAPI/sprites
License: Repository is CC0 1.0 Universal
Copyright: All Pokemon images are Copyright The Pokemon Company
Source: ml-explore/mlx-examples
License: MIT License (Apple Inc.)
This server cannot be deployed
MCP server for Qwen Image 3 AI image generation
Capability registry for the agentic economy. Semantic search over verified MCP server listings.
Cloud-hosted MCP server for durable AI memory
