# photographi-mcp
<!-- mcp-name: io.github.prasadabhishek/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](https://github.com/prasadabhishek/photo-quality-analyzer)**) 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
> [!NOTE]
> **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](https://github.com/prasadabhishek/photo-quality-analyzer/blob/mainline/docs/SCIENCE.md)**.
---
## 📸 See It In Action
Here are real examples from actual photo analysis:
### Example 1: Excellent Photo
```json
{
"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
```json
{
"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 |
| :--- | :--- | :--- |
| `analyze_photo` | "Is this dog photo sharp enough for a print?" | Full technical audit of sharpness, focus, and lighting. |
| `analyze_folder` | "How's the overall quality of my 'Vacation' folder?" | Statistical summary identifying the best/worst image groups. |
| `rank_photographs` | "Find the best shot in this burst of the cake." | Ranks files by technical perfection to find the "hero" frame. |
| `cull_photographs` | "Move all the blurry photos to a junk folder." | Automatically cleans up failed shots into a subfolder. |
| `threshold_cull` | "Strictly separate keepers using a score of 0.7." | Binary sorting to isolate professional-grade assets. |
| `get_color_palette` | "What colors are in this sunset for my website?" | Extracts hexadecimal codes for dominant image aesthetics. |
| `get_folder_palettes` | "Generate a moodboard from my 'Forest' shoot." | Batch color extraction for an entire folder. |
| `get_scene_content` | "Which photos contain a 'cat' or 'mountain'?" | Rapid content indexing based on 80+ object categories. |
**[Full API Reference](docs/api-reference.md)**
---
## 🚀 Get Started
### Claude CLI (Fastest)
```bash
claude mcp add --scope user photographi uvx photographi-mcp
```
### Claude Desktop (macOS)
Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"photographi": {
"command": "uvx",
"args": ["photographi-mcp"]
}
}
}
```
### GitHub Copilot CLI
Add to `~/.config/github-copilot/config.json`:
```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=1` or use the `--disable-telemetry` flag.
---
## 📖 Documentation
- **[Setup & Config Guide](docs/setup.md)**: Detailed configuration and troubleshooting.
- **[The Science](https://github.com/prasadabhishek/photo-quality-analyzer/blob/mainline/docs/SCIENCE.md)**: Math and theory behind the quality scoring.
- **[Contributing](CONTRIBUTING.md)**: How to help improve the project.
- **[GitHub Issues](https://github.com/prasadabhishek/photographi-mcp/issues)**: Report bugs or request features.
---
<div align="center">
<p>
<a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
<a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-Compatible-green.svg" alt="MCP Protocol"></a>
<a href="https://glama.ai/mcp/servers/@prasadabhishek/photographi-mcp"><img width="380" height="200" src="https://glama.ai/mcp/servers/@prasadabhishek/photographi-mcp/badge" /></a>
<a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.10+-blue.svg" alt="Python 3.10+"></a>
</p>
<p>Built with ❤️ for photographers</p>
</div>
