shutter-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@shutter-mcp scan my photo library and generate a cull report"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
shutter-mcp

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 |
| Recursively count files under a root by extension, size, and mtime range | read-only |
| Aggregate EXIF stats across a library: camera, lens, focal length, ISO, year-month | read-only |
| Flattened EXIF fields for one file | read-only |
| Exact (sha256) or visual (perceptual hash) duplicate groups | read-only |
| Laplacian-variance blur ranking for jpg files | read-only |
| 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-mcpWith pipx:
pipx install shutter-mcpFrom 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/scansClaude 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-shootSecurity model
Read-only. No tool writes, moves, renames, or deletes user files.
cull_reportreturns markdown text; it never writes a file.Root allowlist. The server only accepts
--rootdirectories 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 ( | jpg, jpeg, tif, tiff, png, dng, arw, raf, nef, cr2, cr3 (best effort on RAW) |
Pixel decode ( | 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 pytestTests 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 toolsblur_scoresARead-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_reportARead-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_duplicatesARead-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_statsARead-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_exifARead-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_libraryARead-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
Scored across 6 tools
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.
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.
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.
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
Related MCP Connectors
AI-cull, edit and export RAW photos locally with the imagic desktop app, from any MCP client.
Read-only MCP server over the JENRIKS daily photoblog: one photo per day since 2006. No auth.
MCP server exposing the YourImageShare upload API (upload/list/delete) as tools for AI agents.
Hosted MCP server for AI photo editing: nothing to install, no desktop photo editor needed.
Related MCP Servers
- FlicenseAqualityDmaintenanceAn 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.431-
- AlicenseNot gradedqualityDmaintenanceA local Ollama-backed MCP server that gives coding assistants a portable photo-understanding toolset including photo analysis, OCR, scene inspection, comparison, and metadata extraction.MIT
- AlicenseNot gradedqualityCmaintenanceLocal image manager MCP server for Windows, enabling AI assistants to search, preview, tag, favorite, and sync local images while keeping originals read-only.MIT
- AlicenseBqualityDmaintenanceAn 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.13BSD 2-Clause "Simplified"