Skip to main content
Glama
photographi-mcp

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

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.


Related MCP server: woof

📸 See It In Action

Here are real examples from actual photo analysis:

Example 1: Excellent Photo

Best Shot

{
  "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

Worst Shot

{
  "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


Available Tools

8 tools
photographi_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

    A3.9/5.0

    Scored across 8 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI assistants to browse and search local photo galleries without uploading photos, using metadata-only indexing and local thumbnail serving.
      44 PyPI
      8
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A 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