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
- sweetrb/apple-photos-mcptheir own version, first seen Nov 12, 2026
- alexjmiller5/agent-config-publictheir own version, first seen Oct 2, 2026
- jablonkai/skillstheir own version, first seen Oct 1, 2026
Other versions3 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 3
- sweetrb/apple-photos-mcp★ 50same name
- jablonkai/skills★ 2same name
- 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.
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
- Distinctive: line 38
Search returns candidates.
- Distinctive: line 72
Search for what the photo looks like instead.
- Distinctive: line 88
When a phrase returns nothing, try a plainer visual word.
- Very specific: line 176
Run doctor() before guessing.
“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.
Files
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> --helpThe 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:
search_photosto get candidates.look_at_photoson the top three to five.- 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:
| Signal | What it holds |
| Scene labels | About 1,500 visual words: Sunset, Receipt, Dog, Whiteboard, Crowd |
| Text in image | Every word Apple's OCR read inside the picture |
| Activities | Dining, Hiking, Beach Activity, Celebration |
| Venue types | Restaurant, Cafe, Bar, and cuisine types |
| Place | Reverse geocoded city, state, country, venue name |
| Faces | Only people the user has actually named in Photos |
| Albums, keywords, titles | Only 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 doctorExit codes
A script branches on the number, not the message:
| Code | Means |
| 0 | it worked |
| 1 | something unexpected went wrong |
| 2 | typed wrong, or a write was refused: a missing flag, a bad value, no --confirm, or read only |
| 3 | a photo or album was not found |
| 4 | macOS refused access: Full Disk Access, or Automation for Photos |
| 5 | the engine or Photos failed |
| 10 | the engine could not start: install uv, or set APPLE_PHOTOS_PYTHON |
When something breaks
| Symptom | Cause | Fix |
| Permission denied on the library | No Full Disk Access | System Settings, Privacy & Security, Full Disk Access. Add the app running the server, then fully quit and reopen it. |
| A write fails but reads work | Photos automation not allowed | Approve the one-time popup, or System Settings, Privacy & Security, Automation |
| No preview for one photo | iCloud-only with no cached thumbnail | Open it once in Photos, or export it |
| Library not found | Photos has never run, or a non-default library | Set APPLE_PHOTOS_LIBRARY to the .photoslibrary path |
Run doctor() before guessing. It names which of these it is.
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
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.

