PhotoS

Batch photo processing: compress, convert, EXIF, rename, dedup, cull, galleries

Quick Install

Automated & IDE Setup

Copy the AI prompt to install this server into Claude Code, Cursor, or another agent — or use 1-click editor setup below.

Add to Cursor Add to VS Code

Manual Client & Custom JSON ConfigExpand JSON ▾

Client Config & Setup

Choose your client or environment

Target File:~/Library/Application Support/Claude/claude_desktop_config.json

claude_desktop_config.json

{
  "mcpServers": {
    "photos": {
      "command": "npx",
      "args": [
        "-y",
        "photos"
      ]
    }
  }
}

💡 Paste the JSON block into your client's configuration file under mcpServers, then restart the application.

Documentation Overview

📷 PhotoS

CLI for AI agents, GUI for humans. PhotoS is a cross-platform batch photo toolbox: a full Tkinter GUI — v2.0 workspace with Library / Develop (live pipeline preview + histogram + edit tools beside it) / Export (photo queue + output settings) / Tools modules — and a CLI / REST / MCP surface with one versioned JSON contract for AI agents.

🖥 GUI for humans · ⌨️ CLI for AI agents · pip install photo-s-tools

English · 中文

🤖 Built for AI agents

PhotoS is an AI-agent-ready image pipeline: four integration paths, one versioned JSON contract (schema_version, additive-only — upgrades never break a consumer).

Path	Entry point
MCP server — 25 tools (process / select / hdr / blurfaces / dedup / …)	`claude mcp add photo-s -- photo-s mcp`
Packaged SKILL.md — skill-capable agents, zero extras	`cp -r skills/photo-s ~/.claude/skills/`
REST API — async tasks + SSE progress	`photo-s serve --port 0 --token auto --ready-file x.json`
Python library — no IPC overhead	`from photo_s.engine import batch_process`

Every output carries schema_version; JSON keys are always English; per-file errors never abort the batch; destructive actions require an explicit flag. Full contract: docs/AGENT_API.md.

✨ Features

Feature	GUI	CLI	Description
Batch compress	✅	✅	JPEG/WebP/HEIC/AVIF quality tuning, chroma subsampling (444/422/420)
Target size mode	✅	✅	Auto-tune quality to fit under a target file size
Format convert	✅	✅	JPEG / PNG / WebP / TIFF / BMP / HEIC / AVIF
RAW decode	✅	✅	22+ camera RAW formats, built-in (rawpy/libraw); demosaic algorithm choice, color space (sRGB/AdobeRGB/ProPhotoRGB), 16-bit TIFF output, auto sRGB ICC tagging
Resize / Scale	✅	✅	Max dimensions, percentage, or longest-side cap
Visual preview	✅	—	Live original↔processed preview rendered through the real pipeline
Tone & color	✅	✅	Brightness/contrast/saturation/gamma/sharpen, B&W, sepia
Export sharpen	✅	✅	LR-style output-stage USM, radius scales with output resolution
White balance	✅	✅	Kelvin temperature or gray-card sampling
WB tint axis	✅	✅	Green(-)/magenta(+) G-M axis
Point curves / levels	✅	✅	PCHIP point curves, manual black/white/gamma
3-way color grading	✅	✅	Shadows/midtones/highlights hue + sat zones
HSL split	✅	✅	8 color domains, hue/sat/lum shifts
Point color	✅	✅	Targeted hue/sat/lum around a sampled color + range
Local masks	✅	✅	Named linear/radial/color-range masks + v1.8 AI segmentation (`subject`/`person`/`object:class`), brush strokes (subtract mode), combos (A&B / A-B); 11 scalar + 5 string local adjustments under each
Lens correction	✅	✅	Manual distortion k1, vignette fix, CA fix (pure numpy); named user-maintained lens profiles
Perceptual analysis	✅	✅	Histograms / channel stats / WB lean / exposure / blur (`analyze`)
Vibrance / clarity / texture	✅	✅	Natural saturation, local contrast
Dehaze / vignette / grain	✅	✅	Dark-channel dehaze, radial vignette, film grain
Exposure	✅	✅	Stops adjustment or normalize-to-target auto exposure
Auto levels	✅	✅	2% clip histogram stretch
Highlight recovery	✅	✅	LR-style: compress flat clipped highlights back to visible gradient
LOG recovery	✅	✅	SLOG3/CLOG3/LOGC3/DLOG/VLOG/HLG (1D LUT, no deps)
LUT grading	✅	✅	.cube trilinear (plugin adds tetrahedral + 5 film presets)
AI auto-tone	—	✅¹	Plugin: CLIP+MLP predicts 9-field LR params + confidence, RAG boost, optional Qwen3-VL aesthetic score & advisor (`photo-s-plugin-auto-tone[model]`)
Denoise	✅	✅¹	NLM (`[enhance]` extra)
Auto-straighten	✅	✅¹	Level the horizon, confidence-gated (`[enhance]` extra)
HDR merge	✅	✅¹	Exposure fusion, handheld alignment (`[enhance]` extra)
Face blur	✅	✅¹	Blur or pixelate faces, Haar cascade (`[enhance]` extra)
Cutout	✅	✅	Background removal → alpha: AI segmentation (`subject`/`person`/`object:class`) or color key (`color:R,G,B[tol,feather,invert]` — white-bg text/logo); PNG/WebP/TIFF/AVIF/HEIC (JPEG errors per file)
Crop / Rotate / Flip / Pad	✅	✅	Unified aspect crop + arbitrary geometry
Print size	✅	✅	Center-crop + exact print pixels at a DPI
Smart rename	✅	✅	Date/camera/sequence templates
Auto folder organize	✅	✅	Date/camera subfolder creation
Watermark	✅	✅	Text + image overlay, 7 positions
Multi-size output	✅	✅	One input set, N labeled outputs
Metadata tagging	✅	✅	Rating/keywords/caption batch tag (UserComment)
Metadata filter	✅	✅	Find photos by rating/keywords
Metadata import	—	✅	Batch write from spreadsheet
Culling	✅	✅	Exposure/sharpness filter (GUI keeps only matches, undoable)
Select (keeper)	✅	✅	Sort by rating — keep/reject thresholds (≥4 keep, ≤2 reject)
Burst keep-sharpest	✅	✅	Keep the sharpest of a burst
Checksum manifest	✅	✅	SHA-256 archive integrity + verify
HTML gallery	✅	✅	Self-contained index.html + thumbnails
Presets	✅	✅	Save/load named configs + built-in `lr-look` (LR-style grade: S-curve, vibrance, export sharpen)
Multi-profile batch	—	✅	One input set, N output profiles
Parallel processing	✅	✅	Multi-threaded
JSON output	—	✅	Machine-readable output for AI agents
Config file	—	✅	TOML defaults
EXIF edit	—	✅	Batch copyright/author/GPS
Preset apply	—	✅	One-click apply a saved style
EXIF date shift	—	✅	Timezone/camera clock fixes
Privacy scrub	—	✅	Strip EXIF + ICC + GPS
Sync date	—	✅	Output mtime ← EXIF datetime
Folder watch	✅	✅	Auto-process new files (`[watch]` extra)
Auto-rotate	✅	✅	EXIF Orientation-based
Image dedup	✅	✅	Perceptual hash duplicate detection
Quality metrics	✅	✅	SSIM / blur score
CSV report	—	✅	Per-file stats
Integrity check	—	✅	Corrupt file scan
Contact sheet	✅	✅	Grid montage
Color management	—	✅	sRGB / CMYK flatten
REST API	—	✅	HTTP server for agents (async tasks + SSE progress)
Plugin system	—	✅	Third-party plugin support
Official plugin manager	—	✅	list/install/info/fetch + pip install
MCP server	—	✅	25 tools to MCP clients (Claude Desktop / Claude Code / any MCP client)
Batch benchmark	—	✅	Worker-scaling measurement

¹ Denoise / auto-straighten / HDR / face blur need an optional dependency: pip install photo-s-tools[enhance] (opencv-python-headless). When missing, these features give a clear install hint and the rest keeps working.

📦 Install

Terminal

pip install photo-s-tools            # core — RAW decode (rawpy) built in
pip install "photo-s-tools[enhance]" # + opencv: face blur / HDR / denoise / straighten
pip install "photo-s-tools[tiff16]"  # + tifffile: 16-bit RAW → TIFF output
pip install "photo-s-tools[mcp]"     # + MCP server (Python 3.10+)

Zero-install (uvx): uvx --from photo-s-tools photo-s --help · uvx --from "photo-s-tools[mcp]" photo-s mcp

🚀 Quick start

bash

photo-s batch 'RAW/*.ARW' --format jpeg -o out/ -q 90   # batch RAW → JPEG
photo-s batch 'RAW/*.ARW' -o out/ -q 95 --jpeg-subsampling 444 \
  --raw-demosaic amaze                                # max quality RAW → JPEG
photo-s batch 'RAW/*.ARW' -o out/ --preset lr-look     # LR-style grade out of the box
photo-s compress *.jpg --target-size 5MB -j 8           # auto-tune to ≤5MB
photo-s select ~/shoot/ -r --selects-dir picks --rejects-dir bin --dry-run
photo-s hash ~/deliver/ -o manifest.csv --verify manifest.csv

photo-s --help lists all 34 commands. Language: --language en|zh|auto.

🧭 Documentation

Doc	Contents
`docs/FEATURES.md`	Full inventory — 34 CLI commands, engine pipeline
`docs/AGENT_API.md`	Agent contract: JSON shapes, exit codes, REST, MCP
`docs/PLUGINS.md`	Plugin system: SCUNet denoise, LUT, write your own
`docs/GUI_CHANGES.md`	GUI behavior & interface contract
`docs/ROADMAP.md`	Version roadmap (v1.6.0: Lightroom-direction grading)

Names: PyPI distribution photo-s-tools (the obvious photo-s is taken) · CLI command photo-s · Python package photo_s · brand PhotoS.

⚠️ Limitations

PhotoS is a batch / delivery pipeline, not an interactive editor — no RAW-domain editing. Local editing is spec-driven: named masks (linear/radial/color/AI segmentation/brush strokes/combos) + local adjustments under masks, all as compact strings that serialize through CLI/REST/MCP/presets.

On-device inference, no cloud. Denoise model weights (SCUNet) download to your machine on first use; nothing is uploaded.
Licensing. Official code and most official model weights (incl. the SCUNet checkpoint) are MIT — free for commercial use. Exception: the auto-tone plugin's weights are CC-BY-NC 4.0 (non-commercial, trained on personal Lightroom edits; see plugins/auto-tone/LICENSE-WEIGHTS.txt). Third-party plugins and models carry their own licenses; verify before redistribution.

📄 License

MIT

Related MCP Servers

View all in Developer Tools View all alternatives

Reviews

No reviews yet — be the first to share how this listing worked for you.

Frequently Asked Questions about PhotoS

Add the following block to your claude_desktop_config.json under mcpServers: "mcpServers": { "photos": { "command": "npx", "args": ["-y", "PhotoS"] } }

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:

Live Dynamic SVG Preview

Markdown (GitHub README)

[![AllMCPs](https://allmcps.com/api/badge/photos?style=directory)](https://allmcps.com/mcp/photos)

HTML Embed

<a href="https://allmcps.com/mcp/photos"><img src="https://allmcps.com/api/badge/photos?style=directory" alt="PhotoS on AllMCPs" /></a>

Technical Specs & Signals

CategoryDeveloper Tools

27Quality signal: Emerging · 27/100How this signal is calculated ▾

Server availabilityNot measured

Not scored for repo-hosted servers — we can't reach the running server, only its GitHub page. Hosted MCP endpoints are health-checked live.

Verified ownership8/20

Documentation & tools11/30

Adoption & activity1/15

Community engagement0/10

A guidance signal from public completeness & health data — not a user rating. New listings start lower and rise as they add docs, get verified, and grow adoption. Signals we can't observe for a listing are skipped, not counted against it.

★ Featured

AllMCPs Server

The official MCP server for AllMCPs.com - submit and manage tools directly from your AI. The open directory for MCP servers. Connect Claude, Cursor, Windsurf, and AI agents to databases, tools, files, and APIs. Explore 10,000+ servers. AllMCPs is the premier, open directory for discovering, evaluating, and installing Model Context Protocol (MCP) servers to equip AI agents and LLMs with real-world superpowers.

Explore Server →

Own this project?

This directory is pre-filled from public sources. Claim via GitHub README, site badge, or DNS TXT to unlock edit access and the Official badge and attach your website — proof is checked automatically, then reviewed by our team.

Free dofollow backlink: add your website and place the AllMCPs badge on it — no claim needed. We detect it automatically and keep it verified as long as the badge stays live.

Claim & get free dofollow

Share & Embed

Add our SVG badge (dark/light directory styles) or embeddable widget to your site.

Explore more

More in 💻 Developer Tools →Best MCP servers for Developers →Alternatives to PhotoS →Install in Claude Desktop Install in Cursor Install in VS Code