list-keywords

Create an album — or return the existing one of that name (created: false), so re-running a filing workflow never piles up duplicates.

Run a full setup diagnostic — six checks: the resolved Python interpreter (path + version — warns when it's older than the required 3.11, with brew install python@3.12 advice), osxphotos installation, sidecar mode (persistent vs one-shot fallback, plus the last respawn), the write-tools gate (enable

Export one or more photos by UUID to a destination directory.

Group exact duplicates using Photos' own fingerprint-based detection — the same data behind Photos' Duplicates album, no export or hashing required.

Get full metadata for a single photo by UUID.

Get full metadata for a batch of photos (up to 50) in one call — the batch equivalent of get-photo, for dedupe reviews, EXIF audits, and captioning passes.

Get the photos currently selected in the Photos.app window — the bridge from "act on these photos" to UUIDs you can feed into get-photos, get-thumbnail, export, or add-to-album.

Return one photo as an inline viewable image — an MCP image content block (base64 JPEG/PNG) that vision-capable clients render directly. Serves the preview derivatives Photos has already generated, so nothing is exported and originals aren't transferred. Prefer this over export whenever the goal is

Verify osxphotos is installed and the Photos library can be opened.

Import image/video files from disk into the Photos library, optionally straight into an existing album. Add-only: nothing is modified or deleted, and source files stay where they are (Photos copies them in).

High-level stats about the Photos library.

List all albums in the library.

List all folders in the library.

List people detected by Photos face recognition, sorted by photo count.

Search the library with combinable filters. Returns photo summaries with UUIDs — use get-photo for full details on a specific match.

Remove photos from an album — never from the library (they remain in All Photos and every other album).

Add and/or remove keywords on a photo with union semantics: the photo's current keywords are read first and the edits merged in, so keywords you don't mention are always preserved — never a blind replace.

Fix a photo's date/time — set an absolute date or shift by a number of seconds. Dry run by default: nothing is written until you pass dryRun: false. This rewrites the date in the Photos library database only (the same thing Photos.app's Adjust Date & Time does) — the file's EXIF is never modified.

Set a photo's title, description, and/or favorite flag. Only the fields you pass are touched.