photographi-mcp
photographi-mcp
Fast, private, and grounded technical photo analysis for AI applications.
photographi-mcp is an MCP server that enables AI models and LLM-powered tools to perform technical analysis on local photo libraries. It runs computer vision models directly on your hardware (powered by photo-quality-analyzer-core) to evaluate sharpness, focus, and exposure—enabling capabilities like automated culling, burst ranking, and metadata indexing without requiring a cloud upload.
⚡ Why photographi?
Technical First: Purpose-built for objective metrics (sharpness, lighting, focus). It provides technical data for evaluating image quality.
Token Efficient: Save model context by pre-filtering technical metadata locally. Only the most relevant insights are sent to the AI application, keeping sessions fast and lean.
Privacy First: All analysis happens 100% locally on your machine.
Low Latency: Built for efficient processing, allowing for rapid ranking and technical feedback on local photo folders.
👁️ What It Analyzes
Smart Focus: Detects subjects and verifies they're sharp
Exposure: Catches blown highlights and blocked shadows
Gear-Aware: Knows your lens's sweet spot for optimal sharpness
Composition: Evaluates framing and subject placement
Quality Alerts: Flags motion blur, diffraction, high ISO noise
Technical vs. Artistic: This tool is strictly objective. It evaluates photos based on technical metrics and computer vision (sharpness, exposure, noise, etc.). It does not understand artistic intent, aesthetics, or "vibe." A blurry, underexposed photo may be an artistic masterpiece, but photographi will correctly flag it as technically poor.
For the science and math behind it, see the Technical Documentation.
Related MCP server: woof
📸 See It In Action
Here are real examples from actual photo analysis:
Example 1: Excellent Photo

{
"overallConfidence": 0.89,
"judgement": "Excellent",
"keyMetrics": {
"sharpness": 0.94,
"exposure": 0.87,
"composition": 0.85
}
}Verdict: Tack sharp on subject, well exposed, strong composition.
Example 2: Poor Photo

{
"overallConfidence": 0.20,
"judgement": "Very Poor",
"keyMetrics": {
"sharpness": 0.30,
"focus": 0.07,
"exposure": 0.0
}
}Verdict: Missed focus on subject, severe underexposure/black clipping, and excessive headroom.
🛠️ Tools (MCP)
photographi-mcp enables AI models to perform deep technical audits through these standardized tools:
Tool | AI "Intent" Example | Action / Insight Provided |
| "Is this dog photo sharp enough for a print?" | Full technical audit of sharpness, focus, and lighting. |
| "How's the overall quality of my 'Vacation' folder?" | Statistical summary identifying the best/worst image groups. |
| "Find the best shot in this burst of the cake." | Ranks files by technical perfection to find the "hero" frame. |
| "Move all the blurry photos to a junk folder." | Automatically cleans up failed shots into a subfolder. |
| "Strictly separate keepers using a score of 0.7." | Binary sorting to isolate professional-grade assets. |
| "What colors are in this sunset for my website?" | Extracts hexadecimal codes for dominant image aesthetics. |
| "Generate a moodboard from my 'Forest' shoot." | Batch color extraction for an entire folder. |
| "Which photos contain a 'cat' or 'mountain'?" | Rapid content indexing based on 80+ object categories. |
🚀 Get Started
Claude CLI (Fastest)
claude mcp add --scope user photographi uvx photographi-mcpClaude Desktop (macOS)
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"photographi": {
"command": "uvx",
"args": ["photographi-mcp"]
}
}
}GitHub Copilot CLI
Add to ~/.config/github-copilot/config.json:
{
"mcp_servers": {
"photographi": {
"command": "uvx",
"args": ["photographi-mcp"]
}
}
}🔒 Privacy & Telemetry
photographi is built on a Privacy-First philosophy.
Anonymized Aggregates Only: We never collect filenames, paths, or EXIF data.
Total Transparency: Audit our collection logic directly in
analytics.py.Opt-Out: Set the environment variable
PHOTOGRAPHI_TELEMETRY_DISABLED=1or use the--disable-telemetryflag.
📖 Documentation
Setup & Config Guide: Detailed configuration and troubleshooting.
The Science: Math and theory behind the quality scoring.
Contributing: How to help improve the project.
GitHub Issues: Report bugs or request features.
Available Tools
8 toolsphotographi_analyze_folderA
Batch analyzes all images in a folder with high concurrency (4-8 images at once). Returns quality scores and judgements for each image. Default limit is 100 images per call. Use 'limit' and 'offset' for pagination. If 'nextOffset' is in the response, call again with that offset. Perfect for understanding the overall quality distribution of a shoot.
Inputs: folder_path (required), metrics, enable_subject_detection, model_size, +3 more. Returns: object
photographi_analyze_photoA
Analyzes a single photo for technical quality (sharpness, exposure, noise, etc.). Returns overall score, judgement, and per-metric breakdowns. Use this for detailed inspection of individual images. For batch analysis, use photographi_analyze_folder.
Inputs: image_path (required), metrics, enable_subject_detection, model_size, +1 more. Returns: object
photographi_cull_photographsA
Culls low-quality images by moving them to a 'culled_photos' subfolder. Images ABOVE the threshold (default 0.4) stay in the original folder. Images BELOW the threshold are moved to culled_photos/. Processes 100 images per call by default. Use 'limit' and 'offset' for pagination. Mode options: 'move' (default), 'xmp' (sidecar tagging), or 'both'.
Inputs: folder_path (required), threshold, mode, enable_subject_detection, +3 more. Returns: object
photographi_get_color_paletteA
Extracts a representative color palette from a single image using K-Means clustering. Returns a list of hex color codes (e.g., ['#FF5733', '#33FF57', ...]). Default is 5 colors. Use this for design inspiration or color grading reference.
Inputs: image_path (required), colors. Returns: object
photographi_get_folder_palettesB
Extracts color palettes from multiple images in a folder. Processes 20 images per call by default. Use 'limit' and 'offset' for pagination. Returns a map of filename → color palette. Useful for building color-based galleries or moodboards.
Inputs: folder_path (required), colors, limit, offset. Returns: object
photographi_get_scene_contentA
Detects objects in a photo using YOLO (e.g., person, dog, car, etc.). Returns a simple list of object labels. Use this for quick scene indexing or content-based search. For full quality analysis with subject-aware metering, use photographi_analyze_photo.
Inputs: image_path (required). Returns: object
photographi_rank_photographsA
Ranks photos by technical quality and returns the top_n best images. Uses high concurrency to process up to 100 images per call (default limit). Ideal for burst sequences or finding hero shots. Returns detailed metrics for each top image. For full folder analysis, use photographi_analyze_folder instead.
Inputs: folder_path (required), top_n, limit, offset, +4 more. Returns: object
photographi_threshold_cullA
Binary threshold culling: moves images below min_confidence (default 0.6) to a 'rejects' subfolder. Images ABOVE the threshold stay in the original folder. Similar to photographi_cull_photographs, but uses a higher default threshold and 'rejects/' folder name for stricter filtering. Processes 100 images per call. Mode options: 'move', 'xmp', or 'both'.
Inputs: folder_path (required), min_confidence, mode, enable_subject_detection, +3 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Most tools have distinct purposes, but 'cull_photographs' and 'threshold_cull' are very similar, differing only in default thresholds and folder names, which could cause misselection. 'rank_photographs' and 'analyze_folder' also have overlapping functionality.
All tools share the 'photographi_' prefix and generally follow a verb_noun pattern. However, 'cull_photographs' and 'threshold_cull' are inconsistent in structure (verb_noun vs adjective_verb), breaking the otherwise predictable naming convention.
With 8 tools covering analysis, culling, ranking, color extraction, and scene detection, the count is well-scoped for a photography MCP server. Each tool serves a clear role without being excessive or insufficient.
The tool set covers core photography workflows: single/batch analysis, culling, ranking, color palettes, and object detection. Minor gaps exist (e.g., no tool for metadata extraction or direct editing), but these are acceptable for the server's stated purpose.
Maintenance
Related MCP Connectors
Image/video analysis: NSFW detection, object detection, thumbnails
Private cross-media memory for AI assistants: recommendations, progress and controlled actions.
Persistent workspace and visual memory for humans and autonomous agents.
Personal asset search engine: everything you make or upload is searchable by what's inside it.
Related MCP Servers
- AlicenseBqualityCmaintenanceA Pinterest Model Context Protocol (MCP) server for image search and information retrieval352MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to browse and search local photo galleries without uploading photos, using metadata-only indexing and local thumbnail serving.44 PyPI8MIT
- AlicenseAqualityCmaintenanceEnables natural language search of local photo archives using AI-powered semantic understanding, with integration into Claude Desktop via the Model Context Protocol.42MIT
- AlicenseNot gradedqualityDmaintenanceA privacy-first personal context engine that ingests personal photos and message exports, extracts cited facts, and serves a queryable profile over MCP for natural-language questions like 'when did I last see Sarah?'.MIT