Click on "Install 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., "@semantic-image-search-mcp find photos of dogs on beaches"
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.
Search your photo archive using natural language with AI-powered semantic understanding. Built as an MCP (Model Context Protocol) server for seamless integration with Claude Desktop.
Semantic Search: Find images by describing what's in them, not just filenames
Zero Configuration: No manual tagging required - works out of the box
EXIF Metadata: Automatically extracts camera settings, dates, and GPS data
Fast Indexing: Optimized for Apple Silicon (MPS) and NVIDIA GPUs (CUDA)
Claude Integration: Works natively with Claude Desktop via MCP
Privacy First: Runs 100% locally - your photos never leave your machine
Cloud-Synced Libraries: Index "online-only" files (OneDrive Files On-Demand, iCloud Drive, Dropbox) without keeping the whole library on disk - change detection reads placeholder metadata, so reindexing never re-downloads what it already knows
Incremental & Scheduled Reindexing: Embeds only new or changed photos, with a scheduler agent to keep the index current automatically
Related MCP server: Claude RAG MCP Pipeline
# Clone the repository
git clone https://github.com/himalayantrust/semantic-image-search-mcp
cd semantic-image-search-mcp
# Create virtual environment
python3 -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt# Copy example configuration
cp config.yml.example config.yml
# Edit config.yml with your photo archive path
nano config.yml # or use your preferred editorMinimal configuration:
archive_path: "/path/to/your/photos"# Run initial indexing
python3 -c "
import asyncio
from pathlib import Path
from src.config import Config
from src.indexer import ImageIndexer
async def index():
config = Config.from_yaml(Path('config.yml'))
indexer = ImageIndexer(config)
stats = await indexer.index_archive()
print(f'Indexed {stats[\"indexed\"]} images')
asyncio.run(index())
"Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"semantic-image-search": {
"command": "python3",
"args": ["/absolute/path/to/photo-library/run_server.py"],
"env": {
"PYTHONPATH": "/absolute/path/to/photo-library"
}
}
}
}After updating the configuration, restart Claude Desktop. You should see the semantic-image-search server connected in the MCP section.
Ask Claude:
Search my photos for images with people in classroomsFind photos of mountain landscapes taken in 2024Show me portraits with natural lightingGet detailed information about image abc123def456Show me statistics about my photo archiveReindex my photo archiveIf your archive lives in a cloud folder with "online-only" files (OneDrive Files On-Demand, iCloud Drive "Optimize Storage", Dropbox online-only), you can index the whole library without keeping it all on disk.
How online-only indexing works. The indexer detects new or changed files from each file's size and modification time, which it reads from the placeholder without downloading the file. Only images that are genuinely new or changed get materialised and embedded, so reindexing an unchanged library downloads nothing.
Folder-by-folder driver. For a large library on a storage-constrained machine, index_library.py indexes one allow-listed folder at a time so you can free space between folders:
# Index specific top-level folders (smallest first validates fast)
python3 index_library.py --config config.yml \
--only "2019 Trip" --only "2020 Trip" --no-evict
# Or drive it from an allow-list file (one folder name per line)
cp folders.allow.example.txt folders.allow.txt # then edit
python3 index_library.py --config config.yml --folders folders.allow.txt--only NAME (repeatable) or --folders FILE: which top-level folders to index
--max-gb N: warn before indexing a folder larger than N GB (default 50)
--no-evict: don't prompt to free space between folders (use for unattended runs)
After a folder is indexed, its thumbnails and embeddings are stored locally, so you can safely return the originals to online-only ("Free Up Space") and reclaim the disk. Only image files are ever read, so videos and other large files in the same tree are never downloaded.
Exact, training-free search index. The FAISS index uses IndexFlatL2 (exact nearest-neighbour) for libraries up to ~200k images. It needs no training step and searches tens of thousands of images in a few milliseconds.
reindex_missing.py embeds only new or changed images (using the size/mtime detection above) and rebuilds the search index:
python3 reindex_missing.pyTo run it on a schedule, auto_reindex.sh wraps it with logging, and the bundled launchd agent runs it for you. com.himalayantrust.photo-reindex.plist is set to run weekly - edit its StartCalendarInterval for a different cadence:
cp com.himalayantrust.photo-reindex.plist ~/Library/LaunchAgents/
launchctl load -w ~/Library/LaunchAgents/com.himalayantrust.photo-reindex.plistIncremental runs download and embed newly added photos and leave them local until you next free space. For a large new drop (tens of GB), use the attended index_library.py so eviction keeps peak disk in check.
The server exposes four tools to Claude:
search_imagesSearch images using natural language queries with optional filters.
Parameters:
query (string, required): Natural language description
limit (integer, optional): Max results (default: 10, max: 100)
date_from (string, optional): Filter by date (ISO format: YYYY-MM-DD)
date_to (string, optional): Filter by date (ISO format: YYYY-MM-DD)
folder_pattern (string, optional): Filter by folder path
Example:
{
"query": "person standing in a room",
"limit": 5,
"date_from": "2024-01-01"
}get_image_infoGet detailed metadata for a specific image.
Parameters:
image_id (string, required): Unique image identifier
reindex_archiveRe-index the photo archive for new or modified images.
Parameters:
force (boolean, optional): Force re-index all images (default: false)
get_archive_statsGet statistics about the indexed photo archive.
No parameters required.
# Path to your photo archive (required)
archive_path: "/path/to/photos"
# Directory for storing index data (optional)
data_dir: "./data"
# CLIP model configuration
clip:
# Model to use for embeddings
model_name: "openai/clip-vit-base-patch32" # or "openai/clip-vit-large-patch14"
# Device for inference
device: "auto" # auto, mps, cuda, or cpu
# Batch size for processing
batch_size: 32 # Increase for more RAM/VRAM
# Search configuration
search:
default_limit: 10
max_limit: 100
similarity_threshold: 0.0 # 0.0 = show all ranked results
# Thumbnail configuration
thumbnails:
enabled: true
max_size: 512
quality: 85CLIP: OpenAI's vision-language model for understanding images
FAISS: Facebook's vector similarity search library
SQLite: Lightweight database for metadata storage
MCP: Model Context Protocol for Claude integration
PyTorch: ML framework with Apple Silicon (MPS) support
Indexing:
Scans your archive for image files
Extracts EXIF metadata (camera, date, location, etc.)
Generates semantic embeddings using CLIP
Stores embeddings in FAISS vector index
Saves metadata in SQLite database
Searching:
Converts your text query to an embedding
Searches FAISS index for similar image embeddings
Applies filters (date, folder, etc.)
Returns ranked results with similarity scores
MCP Integration:
Exposes search tools to Claude via stdio protocol
Claude can search, get details, and manage your archive
All processing happens locally on your machine
Small archives (< 1,000 images): ~30 seconds
Medium archives (1,000 - 10,000 images): 2-5 minutes
Large archives (10,000+ images): 10-30 minutes
Typical query: 200-500ms
With filters: 300-700ms
Base: ~200MB (model + server)
Per 10,000 images: ~20MB (embeddings + metadata)
Run indexing first:
python3 -c "import asyncio; from src.indexer import ImageIndexer; from src.config import Config; from pathlib import Path; asyncio.run(ImageIndexer(Config.from_yaml(Path('config.yml'))).index_archive())"Check Claude Desktop logs: ~/Library/Logs/Claude/mcp*.log
Verify absolute paths in claude_desktop_config.json
Ensure config.yml exists in the project directory
Check mcp-server.log for errors
Reduce batch_size in config.yml (uses less memory, slightly slower)
Check that MPS/CUDA is being used (look for "Using Apple Silicon MPS" message)
Close other applications to free up RAM
Ensure virtual environment is activated:
source venv/bin/activate # On Windows: venv\Scripts\activatepytest tests/black src/
ruff check src/Search historical photo collections by content, era, or subject matter.
Find photos from specific trips, locations, or events for reports and social media.
Quickly locate stock footage and images matching creative briefs.
Organize and search large portfolio collections by visual content.
Find specific images in large datasets for analysis and publication.
Contributions welcome! Please:
Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request
MIT License - see LICENSE file for details.
Built on CLIP by OpenAI
Uses FAISS by Meta AI Research
Implements Model Context Protocol by Anthropic
For issues and questions:
GitHub Issues: https://github.com/himalayantrust/semantic-image-search-mcp/issues
Email: info@himalayantrust.org
Built with love by the Himalayan Trust team 🏔️
Get statistics about the indexed photo archive.
Provides an overview of your photo collection including total count, date range, storage size, and distribution by camera and folder.
Returns: Dictionary containing: - success: Whether the operation succeeded - total_images: Total number of indexed images - date_range: Earliest and latest photo dates - total_size_bytes: Total storage used in bytes - total_size_gb: Total storage used in gigabytes - top_cameras: Most common camera models - top_folders: Folders with the most images
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does disclose the return structure including a success flag, and implies the archive must already be indexed. However, it does not explicitly state that the operation is non-mutating, nor does it mention any potential side effects. Still, the detailed return list provides useful transparency about what the tool yields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and appropriately sized. It opens with a one-sentence purpose, adds a brief contextual overview, then lists the return fields in a clean bulleted format. Every part serves a purpose, and the return field list is essential given the lack of an output schema. It is front-loaded with the most important information first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the tool has no parameters and no output schema, the description fully compensates by enumerating all return fields with their meanings. It also clarifies the scope ('indexed photo archive') and provides enough context to understand what the tool does and returns. For a simple stats query, this is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the input schema is empty. Per the rubric, a 0-parameter tool gets a baseline of 4. The description does not need to add parameter semantics, and it appropriately focuses on the output. No parameter documentation is required.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with a clear statement: 'Get statistics about the indexed photo archive.' It specifies the resource (photo archive) and the action (get statistics), and lists the specific types of statistics (total count, date range, storage size, distribution by camera and folder). This clearly distinguishes it from sibling tools like search_images (searching) and get_image_info (single image details).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use this tool: when you need an overview of the entire photo archive. It states it 'Provides an overview of your photo collection'. However, it does not explicitly mention alternatives or exclusions (e.g., 'for details on a single image, use get_image_info'), so it lacks explicit when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed metadata for a specific image.
Retrieves comprehensive information about an image including EXIF data, camera settings, location, and file details.
Args: image_id: Unique identifier for the image (obtained from search results)
Returns: Dictionary containing: - success: Whether the operation succeeded - image: Complete metadata including: - filepath: Full path to the image file - filename: Name of the file - folder: Folder containing the image - width/height: Image dimensions - date_taken: When the photo was taken (if available) - camera_make/model: Camera information - lens_model: Lens used - focal_length: Focal length in mm - aperture: F-stop value - iso: ISO sensitivity - shutter_speed: Exposure time - gps_latitude/longitude: Location coordinates (if available) - tags: Associated tags
| Name | Required | Description | Default |
|---|---|---|---|
| image_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of transparency. It discloses the return structure in detail, including a success flag and optional fields (e.g., gps if available), giving a good sense of the operation's output. It does not explicitly state the operation is read-only or describe error conditions, but the 'get' verb and success flag imply a safe, well-defined behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, followed by structured Args and Returns sections. Although it lists many metadata fields, this is necessary because there is no output schema to document the return value, so every detail earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without an output schema or annotations, the description must be self-sufficient, and it is. It covers input semantics, return format comprehensively, and notes optional availability of certain fields. The absence of explicit error handling is mitigated by the success flag, making it complete for a simple get-by-id tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only defines image_id as a required string with no description (0% coverage). The description compensates by explaining that it is a 'Unique identifier for the image (obtained from search results)' and clarifies how it is used to fetch the metadata, adding crucial meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb 'Get' and resource 'detailed metadata for a specific image', then enumerates metadata categories (EXIF, camera settings, location, file details). This clearly distinguishes it from siblings like search_images, which finds images.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context by stating that image_id is 'obtained from search results', implying usage after a search. However, it does not explicitly mention when not to use this tool or name alternative tools such as get_archive_stats, leaving room for ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Re-index the photo archive for new or modified images.
Scans the archive for new or changed images and updates the search index. This should be run after adding new photos to the archive.
Args: force: If True, re-index ALL images (slow). If False, only index new or modified images (default, recommended)
Returns: Dictionary containing: - success: Whether indexing succeeded - total_images: Total number of images found - indexed: Number of images indexed - errors: Number of errors encountered - duration_seconds: Time taken to complete indexing
| Name | Required | Description | Default |
|---|---|---|---|
| force | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It explains the scanning behavior, the impact of force (full re-index, slow), and the return dictionary with success, counts, and errors. It does not mention side effects like index overwriting or permissions, but for this tool the disclosed details are adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a one-sentence summary, a clarifying paragraph, then Args and Returns sections. It is front-loaded and contains no fluff or redundant information. Every sentence contributes to understanding the tool's purpose, usage, and behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one parameter, no annotations, and no output schema, this description is thorough. It explains what the tool does, when to run it, the meaning of the only parameter, and the shape of the return value. The agent has enough information to select and invoke it correctly without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides only a boolean 'force' with a default, but the description adds meaningful semantics: 'If True, re-index ALL images (slow). If False, only index new or modified images (default, recommended).' This compensates for the 0% schema description coverage and clarifies the parameter's effect and performance trade-off.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Re-index the photo archive for new or modified images.' The verb 're-index' and resource 'photo archive' are specific. It distinguishes itself from sibling tools like search_images and get_archive_stats, which serve different purposes (querying and stats).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: 'This should be run after adding new photos to the archive.' It also recommends the default behavior (force=False) as the preferred approach. It does not explicitly name alternatives or exclusion cases, but the context is sufficient given the distinct sibling tool purposes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search images using natural language queries with optional filters.
This tool performs semantic search across your photo archive using AI-powered image understanding. It finds images based on their visual content, not just filenames or tags.
Args: query: Natural language search query describing what you're looking for. Examples: "person in a room", "mountain landscape", "children playing", "sunset over water", "food on a table" limit: Maximum number of results to return (default: 10, max: 100) date_from: Filter results to images taken on or after this date (ISO format: YYYY-MM-DD) date_to: Filter results to images taken on or before this date (ISO format: YYYY-MM-DD) folder_pattern: Filter by folder path pattern (e.g., "2024" or "vacation")
Returns: Dictionary containing: - success: Whether the search succeeded - query: The search query used - count: Number of results found - results: List of matching images with metadata and similarity scores
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | ||
| date_to | No | ||
| date_from | No | ||
| folder_pattern | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals key traits: AI-powered semantic search based on visual content rather than filenames/tags, and details the return structure including success, query, count, and results. No contradictions exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with a clear overview, Args section with bullet points, and Returns section. Every sentence adds value, and the format is front-loaded with the core purpose. It is appropriately sized for the complexity of the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with five parameters, no annotations, and no output schema, the description is exceptionally complete. It explains the search semantics, every parameter with examples, and the return value structure, leaving no critical gaps for an agent to invoke and interpret the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides zero description coverage, so the description must explain all parameters. It does so thoroughly, including examples for query ('person in a room'), defaults for limit, date format expectations, and a folder_pattern example. This fully compensates for the lack of schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Search images using natural language queries with optional filters' and further explains it performs semantic search across the photo archive. This specific verb+resource formulation distinguishes it from sibling tools like get_image_info and reindex_archive, which address different operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys a clear use case: finding images by visual content using natural language. It doesn't explicitly mention when not to use it or point to alternatives, but the context is unambiguous enough for an agent to select it appropriately among the given siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool targets a distinct function: semantic search, metadata retrieval, index maintenance, and archive statistics. There is no overlap or ambiguity between them.
All tool names follow a consistent verb_noun pattern with lowercase and underscores: search_images, get_image_info, reindex_archive, get_archive_stats. The verbs are imperative and the nouns are clear.
Four tools is a well-scoped set for a semantic image search server, covering the essential operations without unnecessary bloat. It fits perfectly within the typical 3-15 tool range.
The tool set covers search, metadata retrieval, reindexing, and archive stats, which are the core workflows for this domain. A minor gap is the lack of direct image file access or delete/index management, but these are not critical for search functionality.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Holiday photo MCP server: list and fetch personal holiday photos inline in Claude chat.
Personal asset search engine: everything you make or upload is searchable by what's inside it.
AI-native digital asset management: semantic search, generative image edits, and CDN delivery.
Private persistent memory for Claude, ChatGPT & Gemini via MCP - semantic search, zero-code setup.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Casey-Hemingway/semantic-image-search-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
