Skip to main content
Glama

shutter-mcp

CI MIT License Python 3.11+

shutter-mcp demo: an agent answering a cull question with the cull_report tool

Point Claude, or any MCP client, at a folder of RAW and JPEG files. It can scan the library, break down which cameras and lenses actually got used, find duplicates, flag the shots that are probably blurry, or write a full cull report. It never gets a tool that can touch a file: read-only means read-only, all the way down.

Why this exists: culling tools that touch your shoots ask for a subscription or your client's files on somebody else's cloud. This asks for neither. It reads the metadata and pixels already sitting on your disk and answers in text, not files, and it is deliberately the read-only first step of a bigger local-first project (see Roadmap; the write-capable half is shutter-cull-mcp).

Tools

Tool

Description

Read/write

scan_library

Recursively count files under a root by extension, size, and mtime range

read-only

library_stats

Aggregate EXIF stats across a library: camera, lens, focal length, ISO, year-month

read-only

read_exif

Flattened EXIF fields for one file

read-only

find_duplicates

Exact (sha256) or visual (perceptual hash) duplicate groups

read-only

blur_scores

Laplacian-variance blur ranking for jpg files

read-only

cull_report

Markdown report combining all of the above

read-only

Every tool is read-only. None of them write, move, rename, or delete a file.

Related MCP server: photo-vlm-mcp

Install

Requires Python 3.11+.

With uv (recommended):

uv tool install shutter-mcp

With pipx:

pipx install shutter-mcp

From source, for development:

git clone https://github.com/keivanmalhani/shutter-mcp.git
cd shutter-mcp
uv venv
uv pip install -e ".[dev]"

Usage

shutter-mcp takes one or more --root directories at launch. Every tool call is validated against this allowlist, so the server can only ever see the folders you explicitly grant it.

shutter-mcp --root /path/to/photos --root /path/to/scans

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "shutter-mcp": {
      "command": "shutter-mcp",
      "args": ["--root", "/Users/you/Pictures/2026-shoot"]
    }
  }
}

Claude Code

claude mcp add shutter-mcp -- shutter-mcp --root /Users/you/Pictures/2026-shoot

Security model

  • Read-only. No tool writes, moves, renames, or deletes user files. cull_report returns markdown text; it never writes a file.

  • Root allowlist. The server only accepts --root directories at launch. Every path argument a tool receives is resolved (Path.resolve, symlinks included) and rejected if it falls outside every allowed root, even if a symlink inside the root points elsewhere.

  • No network calls at runtime. Everything happens on your filesystem.

  • No image bytes returned. Tools return paths and metadata only, never base64 or raw pixel data.

  • No telemetry, no analytics.

Format support

Capability

Extensions

EXIF read (read_exif, library_stats)

jpg, jpeg, tif, tiff, png, dng, arw, raf, nef, cr2, cr3 (best effort on RAW)

Pixel decode (blur_scores, visual mode of find_duplicates)

jpg, jpeg, png, tiff

RAW pixel decode (blur scoring and visual dedup on ARW/RAF/etc.) is out of scope for this MVP; EXIF reading works today on both. See Roadmap.

Development

uv pip install -e ".[dev]"
uv run pytest

Tests generate their own fixture images with Pillow at run time; no binary fixtures are committed to the repo.

Roadmap

  • RAW pixel decode (ARW, RAF, and friends) via rawpy, for blur scoring and visual dedup

  • XMP rating/flag writeback so cull decisions show up in Lightroom Classic

  • Integration as the agent interface for the local-first photo culling engine

  • Publish to PyPI and the MCP registry

Family

shutter-cull is the photo engine and shutter-select the video one. shutter-cull-mcp is the side that does write, with human confirmation and undo. This is the read-only one, and that guarantee is structural rather than a promise in the docs.

License

MIT, see LICENSE.

Available Tools

6 tools
blur_scoresA
Read-onlyIdempotent

Score jpg files under a directory for blur using Laplacian variance.

jpg/jpeg only in the MVP. Lower variance means less high-frequency detail, i.e. more likely blurry. Results are sorted ascending (blurriest first); the bottom decile is flagged likely_blurry.

Args: params (BlurScoresInput): Validated input containing: - root (str): Directory of jpg files to score, must be inside an allowed --root - limit (int): Max files to score, default 500, 1-5000

Returns: dict: { "schema_version": 1, "root": str, "files_considered": int, "files_scored": int, "sampled": bool, "sample_note": str | None, "skipped": int, "results": [ {"path": str, "laplacian_variance": float, "likely_blurry": bool}, ... ], # sorted ascending by laplacian_variance } On error: {"schema_version": 1, "error": str}

Examples: - Use when: "Which jpgs in this folder are probably out of focus?" - Don't use when: the library has RAW files only (RAW pixel decode is out of scope for MVP)

Inputs: params (required).

cull_reportA
Read-onlyIdempotent

Build a markdown cull report combining scan, EXIF stats, dupes, and blur.

Runs scan_library, library_stats, find_duplicates (exact mode), and blur_scores under the hood, and combines them into one markdown report: library summary, top EXIF stats, exact duplicate groups, and the blurriest 20 jpg files. Returns markdown text only; never writes a file.

Args: params (CullReportInput): Validated input containing: - root (str): Directory to report on, must be inside an allowed --root

Returns: str: Markdown-formatted report, or "Error: " on failure.

Examples: - Use when: "Give me a summary I can read before I start culling this shoot." - Don't use when: you need machine-readable output (use the individual tools instead)

Inputs: params (required). Returns: result

find_duplicatesA
Read-onlyIdempotent

Find duplicate files under a directory, exact or visually similar.

'exact' mode groups byte-identical files (any file type) by sha256 hash. 'visual' mode groups jpg/png images whose perceptual hash (phash) is within a hamming distance of 5, catching near-duplicate bursts even when bytes differ. Visual mode internally samples up to 3000 newest files for performance on very large libraries. Returns at most 200 duplicate groups; truncated indicates whether more groups exist beyond that cap.

Args: params (FindDuplicatesInput): Validated input containing: - root (str): Directory to scan, must be inside an allowed --root - mode ("exact" | "visual"): Duplicate detection mode, default "exact"

Returns: dict: { "schema_version": 1, "root": str, "mode": str, "files_considered": int, "duplicate_group_count": int, "truncated": bool, "groups": [{"count": int, "files": [str, ...]}, ...], # visual mode additionally includes: files_hashed, sampled, sample_note, truncation_note # exact mode additionally includes: skipped, total_duplicate_groups_found } On error: {"schema_version": 1, "error": str}

Examples: - Use when: "Find exact duplicate files I can safely delete one copy of." - Use when: "Find near-duplicate frames from burst shooting." - Don't use when: you want blur ranking, not duplication (use blur_scores)

Inputs: params (required).

library_statsA
Read-onlyIdempotent

Aggregate EXIF metadata across a library: cameras, lenses, ISO, focal length, dates.

Scans EXIF-readable files (jpg, jpeg, tif, tiff, png, dng, arw, raf, nef, cr2, cr3) under root. If more files are found than sample_limit, the newest files by modification time are sampled and this is noted in the result. Files with no readable EXIF are counted in skipped_no_exif.

Args: params (LibraryStatsInput): Validated input containing: - root (str): Directory to aggregate over, must be inside an allowed --root - sample_limit (int): Max files to inspect, default 2000, 1-50000

Returns: dict: { "schema_version": 1, "root": str, "files_considered": int, "files_sampled": int, "sampled": bool, "sample_note": str | None, "skipped_no_exif": int, "counts_by_camera_model": {str: int, ...}, "counts_by_lens": {str: int, ...}, "counts_by_focal_length_bucket": {str: int, ...}, "counts_by_iso_bucket": {str: int, ...}, "counts_by_year_month": {"YYYY-MM": int, ...}, } On error: {"schema_version": 1, "error": str}

Examples: - Use when: "What cameras and lenses did I use most this year?" - Use when: "Break down this shoot by ISO." - Don't use when: you need per-file EXIF (use read_exif)

Inputs: params (required).

read_exifA
Read-onlyIdempotent

Read flattened EXIF fields for a single image file.

Best effort across jpg, jpeg, tif, tiff, png, dng, arw, raf, nef, cr2, cr3. A file with no EXIF data, or an unsupported extension, is not an error: fields comes back empty with a note explaining why.

Args: params (ReadExifInput): Validated input containing: - path (str): Path to one image file, must be inside an allowed --root

Returns: dict: { "schema_version": 1, "path": str, "fields": { "camera_make": str, "camera_model": str, "lens_model": str, "focal_length": str, "focal_length_35mm_equiv": str, "iso": str, "exposure_time": str, "f_number": str, "exposure_program": str, "date_time_original": str, "date_time": str, "width": str, "height": str, "orientation": str, "software": str, "gps_latitude": float, "gps_longitude": float, }, # only keys actually present in the file are included "note": str | None, # e.g. "no EXIF data found" } On error: {"schema_version": 1, "error": str}

Examples: - Use when: "What lens and settings were used for this specific frame?" - Don't use when: you want aggregates across many files (use library_stats)

Inputs: params (required).

scan_libraryA
Read-onlyIdempotent

Recursively scan a directory and summarize what is in it.

Walks root recursively (symlinks are not followed) and reports file counts by extension, total bytes, and the earliest/latest file modification time. Stops after 50000 files and reports truncation if the library is larger than that. Does not read file contents or EXIF; use library_stats for EXIF aggregates.

Args: params (ScanLibraryInput): Validated input containing: - root (str): Directory to scan, must be inside an allowed --root

Returns: dict: { "schema_version": 1, "root": str, "total_files": int, "total_bytes": int, "counts_by_extension": {".jpg": int, ...}, "earliest_mtime": str | None, # ISO 8601 UTC "latest_mtime": str | None, # ISO 8601 UTC "truncated": bool, "truncation_note": str | None, } On error: {"schema_version": 1, "error": str}

Examples: - Use when: "How many files are in my 2026 shoot folder and how big is it?" - Don't use when: you need EXIF camera/lens breakdowns (use library_stats)

Inputs: params (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.6/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool targets a clearly distinct level of analysis: whole-library scanning, EXIF aggregation, single-file EXIF, duplicate detection, blur scoring, and a combined report. Descriptions explicitly cross-reference each other with 'use X instead' notes, leaving no realistic chance of misselection.

    Naming Consistency4/5

    All names use consistent snake_case, which is the important part. Most are verb_noun or clear noun_phrase (scan_library, read_exif, find_duplicates), though library_stats, blur_scores, and cull_report are noun-first, a minor stylistic deviation.

    Tool Count5/5

    Six tools is well scoped for a photo-library analysis server. Each tool earns its place, and the composite cull_report cleanly wraps the primitives without duplicating their interfaces.

    Completeness4/5

    The analysis surface is strong: scanning, metadata aggregation, per-file inspection, deduplication, blur detection, and a report. Minor gaps remain for a culling workflow — no way to flag, move, or delete rejected files, and blur scoring is jpg-only — but these are acknowledged limitations rather than dead ends for the stated read-only purpose.

    Maintenance

    ActivityNo data
    ResponsivenessSyncing

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      D
      maintenance
      An MCP server for Immich self-hosted photo management that provides AI-accessible tools for browsing, searching, organizing, and managing photo libraries with duplicate detection and safe deletion workflows.
      43
      1
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Local image manager MCP server for Windows, enabling AI assistants to search, preview, tag, favorite, and sync local images while keeping originals read-only.
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      An MCP server that lets LLMs read and edit image metadata (EXIF, GPS, XMP, ICC, IPTC, and more) entirely offline. Supports files, URLs, base64, and includes a browser-based UI for analysis, GPS extraction, and metadata stripping.
      13
      BSD 2-Clause "Simplified"