Apple Photos MCP
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| APPLE_PHOTOS_LIBRARY | No | Path to a specific .photoslibrary. Defaults to last opened. | last opened |
| APPLE_PHOTOS_AUDIT_LOG | No | Path for one JSON line per attempted write. Default off. | off |
| APPLE_PHOTOS_READ_ONLY | No | Removes every write tool from the tool list. Default off. | off |
| APPLE_PHOTOS_EXPORT_DIR | No | Default export folder. Default ~/Downloads/Photos Exports. | ~/Downloads/Photos Exports |
| APPLE_PHOTOS_PREVIEW_PX | No | Longest edge of a preview. Default 640. | 640 |
| APPLE_PHOTOS_PREVIEW_DIR | No | Where previews are cached. Default ~/.apple-photos-mcp/previews. | ~/.apple-photos-mcp/previews |
| APPLE_PHOTOS_PREVIEW_MAX | No | Most items rendered per look_at_photos call. Default 8. | 8 |
| APPLE_PHOTOS_ARCHIVE_ALBUM | No | Album archive_photos moves items into. Default Archived by Claude. | Archived by Claude |
| APPLE_PHOTOS_WRITE_BATCH_MAX | No | Most items a single write may touch. Default 100. | 100 |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server publishes no instructions, or was last inspected before Glama recorded them.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
| experimental | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| search_photosA | Search your entire Apple Photos library using Apple's own on-device index. Natural visual phrases work best: 'sunset beach', 'receipt', 'dinner in Stockholm', 'whiteboard'. Filters narrow before ranking. Args: query: What to find. Leave empty to browse by filter alone. limit: Maximum results (1-100). kind: 'photo' or 'video'. person: Only photos with this named face. album: Only photos in albums whose name contains this. place: Only photos taken somewhere matching this. year: Only photos from this calendar year. date_from: ISO date, inclusive lower bound (YYYY-MM-DD). date_to: ISO date, inclusive upper bound (YYYY-MM-DD). favorites_only: Only items hearted in Photos. screenshots: 'include', 'exclude', or 'only'. include_hidden: Include items in the Hidden album. |
| look_at_photosA | Actually look at photos: renders each one and returns it as an image. Use this on the top few results of every search before answering a "find my photo of X" question. Works even for photos that live only in iCloud, because it reads Apple's own local thumbnails rather than the original. Args: refs: Photo uuids from search results, or exact filenames. size: Longest edge in pixels (128-2048). |
| photo_infoA | Everything known about specific photos: metadata, ML labels, place, albums, faces, and any text Apple read inside the image. Args: refs: Photo uuids or exact filenames. |
| library_statsA | Size and shape of the library: totals, albums, named people, how much is indexed, and how much lives only in iCloud. |
| list_vocabularyA | The visual words this library actually knows. Apple's classifier has a closed vocabulary. When a search finds nothing, this is how to discover the word it does understand instead. Args: starts_with: Only terms beginning with this prefix. limit: Maximum terms to return. |
| export_originalsA | Export full-quality originals to a folder on this Mac. Slow for iCloud-only assets: each one is downloaded first. Nothing is uploaded anywhere. Args: refs: Photo uuids or exact filenames. directory: Absolute destination folder. Defaults to ~/Downloads/Photos Exports. |
| doctorA | Diagnose setup: macOS, Full Disk Access, the library, the index, and whether writes are enabled. Run this first when anything misbehaves. |
| favorite_photosA | Heart photos in Photos, or remove the heart. Args: refs: Photo uuids or exact filenames. favorite: False to un-favorite. |
| set_photo_titleB | Set one photo's title. |
| set_photo_descriptionC | Set one photo's description/caption. |
| add_keywordsA | Add keywords to photos, keeping the ones already there. |
| add_to_albumB | Add photos to an album, creating it if needed. Args: album: Album name. refs: Photo uuids or exact filenames. |
| archive_photosA | The closest thing to deleting that macOS allows. Moves photos into an archive album so they leave the main library view. No app, including this one, can permanently delete photos by script, so the user empties that album by hand. Args: refs: Photo uuids or exact filenames. confirm: The user reads this as deleting their photos. Set true only when they have actually asked for these specific items to go. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 13 tools
Each tool has a clearly distinct purpose: searching, viewing, metadata retrieval, stats, vocabulary, export, diagnostics, and distinct write operations (favorite, title, description, keywords, album, archive). No two tools perform the same action on the same resource.
Most tools follow a verb_noun pattern (search_photos, export_originals, add_to_album, set_photo_title). Minor deviations like photo_info (noun_noun) and doctor (single verb) are understandable but slightly break the uniform pattern.
13 tools is well within the ideal range for a domain-specific server. Each tool covers a meaningful capability without redundancy, making the set feel intentional and manageable.
The surface covers the full lifecycle of interacting with a photo library: searching, examining, editing metadata, organizing into albums, exporting originals, and archiving. The only missing operation—permanent deletion—is explicitly documented as impossible via scripting, making the completeness appropriate for the platform constraints.