agentleFS
thenavidmthenavidm/apple-photos-mcp-cli/SKILL.md

apple-photos

Skill1 starsChanged 50 days agoMITView on GitHub

Search, look at, organize and export the user's own Apple Photos library on this Mac. Use whenever the user wants to find, see, open, favorite, tag, album, archive or export ANY photo or video of theirs: "find my photo of...", "do I have a picture of...", "show me videos from...", "which receipt was that", "add these to an album", "export the original". Also use for questions about the library itself, such as how many photos there are, which places or people appear, or how much lives in iCloud. Everything runs locally and nothing is uploaded.

3 other projects use a version of this.

Adopted by

Most recently taken up by

  • Other versions3 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 3

    1. sweetrb/apple-photos-mcp★ 50same name
    2. jablonkai/skills★ 2same name
    3. alexjmiller5/agent-config-public★ 0same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository2 other files it gives its agents.

The file

We split this skill into the rules it gives an agent

4 rules. 0 are common, 3 are distinctive, and 1 is very specific to this project.

  • 0

    Common

    Most of the 3 edited versions we read keep these.

  • 3

    Distinctive

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Search returns candidates.

    line 38
  2. Distinctive:

    Search for what the photo looks like instead.

    line 72
  3. Distinctive:

    When a phrase returns nothing, try a plainer visual word.

    line 88
  4. Very specific:

    Run doctor() before guessing.

    line 176

“Common” is measured: kept by at least 6 in 10 of the 3 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Apple Photos

The library is read directly from disk on this Mac. Nothing is uploaded, and nothing here can permanently delete a photo.

Two surfaces, same tools

The MCP server is for work inside a conversation. The CLI is for scripting, piping and one-off questions, and costs no context until it is called.

apple-photos-cli library-stats --json
apple-photos-cli search-photos "sunset" --limit 5 --screenshots exclude
apple-photos-cli photo-info --refs IMG_2073.MOV
apple-photos-cli which <words>
apple-photos-cli <command> --help

The command is the tool name with dashes. --select total,videos trims the output, which matters on a library this size.

The one thing that matters

Search returns candidates. It does not return answers.

A filename and a list of labels tell you almost nothing about whether a photo is the one the user meant. So the loop is always:

  1. search_photos to get candidates.
  2. look_at_photos on the top three to five.
  3. Answer based on what you actually saw, naming the file and the date.

Skipping step 2 is how you confidently hand someone the wrong photo. Do not skip it when the user asked you to find something specific.

What is actually being searched

Apple runs machine learning on every photo, on the device, and writes the result into the library. That is the index:

SignalWhat it holds
Scene labelsAbout 1,500 visual words: Sunset, Receipt, Dog, Whiteboard, Crowd
Text in imageEvery word Apple's OCR read inside the picture
ActivitiesDining, Hiking, Beach Activity, Celebration
Venue typesRestaurant, Cafe, Bar, and cuisine types
PlaceReverse geocoded city, state, country, venue name
FacesOnly people the user has actually named in Photos
Albums, keywords, titlesOnly what the user typed themselves

The visual vocabulary is closed. Apple knows "Sunset" but not "golden hour", "Crowd" but not "keynote", "Dog" but not "goofy". If a result comes back with unmatched_terms, that word does not exist in this library and rephrasing the same idea will not help. Read did_you_mean, or call list_vocabulary.

Most libraries have almost no typed metadata. Titles, captions and keywords are usually empty, so searching for what the user calls a photo will fail. Search for what the photo looks like instead.

Finding things

search_photos(query="sunset beach")
search_photos(query="receipt", kind="photo")
search_photos(query="dinner", place="Stockholm", year=2024)
search_photos(query="", person="Anna", favorites_only=True, limit=20)
search_photos(query="whiteboard", screenshots="exclude")

Useful habits:

  • Screenshots are usually noise. About one in five items in a typical library is a screenshot, so pass screenshots="exclude" unless the user wants them.
  • When a phrase returns nothing, try a plainer visual word. "Man on stage" becomes "crowd" or "audience". "My passport" becomes "document".
  • Filters beat clever phrasing. A place plus a year narrows far more reliably than a longer sentence.

Looking

look_at_photos(refs=["<uuid>", "<uuid>", "<uuid>"])

This works even for iCloud-only photos: it reads the thumbnail already on this Mac, so it is fast. Use it freely.

Up to eight items render per call. Ask for a bigger size only when fine detail matters, such as reading text off a receipt.

Organizing

These work by default. If they are missing from the tool list, the server is running with APPLE_PHOTOS_READ_ONLY=1.

favorite_photos(refs=[...])
favorite_photos(refs=[...], favorite=False)
add_to_album(album="Best of Bali", refs=[...])
add_keywords(refs=[...], keywords=["client work"])
set_photo_title(ref="<uuid>", title="Opening keynote")

Each of those is one click to undo in Photos, so none of them ask first.

Archiving, the one that asks

archive_photos(refs=[...], confirm=True)

archive_photos is the only tool that needs confirming: the user approves it over MCP, or confirm: true where the app cannot ask, and --confirm on the CLI. Call it only once the user has asked for those specific items to go.

Nothing deletes. macOS does not let any app delete photos by script. This moves items into an album for the user to empty by hand. Always say so rather than implying the photos are gone.

Exporting

export_originals(refs=[...], directory="~/Desktop/exports")

Full quality originals, written to a folder on this Mac. For iCloud-only photos each one downloads first, so this is much slower than looking. If the user only wants to see a photo, look at it instead.

Library questions

library_stats()          # totals, albums, named people, how much is in iCloud
list_vocabulary()        # the visual words this library knows
photo_info(refs=[...])   # everything about specific items, including OCR text
doctor()                 # run this first whenever anything misbehaves; apple-photos-cli doctor

Exit codes

A script branches on the number, not the message:

CodeMeans
0it worked
1something unexpected went wrong
2typed wrong, or a write was refused: a missing flag, a bad value, no --confirm, or read only
3a photo or album was not found
4macOS refused access: Full Disk Access, or Automation for Photos
5the engine or Photos failed
10the engine could not start: install uv, or set APPLE_PHOTOS_PYTHON

When something breaks

SymptomCauseFix
Permission denied on the libraryNo Full Disk AccessSystem Settings, Privacy & Security, Full Disk Access. Add the app running the server, then fully quit and reopen it.
A write fails but reads workPhotos automation not allowedApprove the one-time popup, or System Settings, Privacy & Security, Automation
No preview for one photoiCloud-only with no cached thumbnailOpen it once in Photos, or export it
Library not foundPhotos has never run, or a non-default librarySet APPLE_PHOTOS_LIBRARY to the .photoslibrary path

Run doctor() before guessing. It names which of these it is.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.