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

[!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.

📸 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 | | :--- | :--- | :--- | | 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

🚀 Get Started

Claude CLI (Fastest)

claude mcp add --scope user photographi uvx photographi-mcp

Claude 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=1 or use the --disable-telemetry flag.

📖 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.