osxphotos-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| LIBRARY | No | Path to the Photos library to use instead of the system library (--library PATH). | |
| ALLOW_WRITE | No | Enable commands that change your library: add-locations, batch-edit, import, push-exif, sync, timewarp (--allow-write). | false |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Tools for the user's Apple Photos library, built on osxphotos. Use search_photos, get_photo, list_albums, list_people_and_keywords and export_photos first. For anything they cannot do, read osxphotos_help and then call run_osxphotos.
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
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| search_photosA | Find photos and videos, newest first. All filters are optional and combine with AND. |
| get_photoB | Full details of one photo: metadata, albums, labels, camera, location and file paths. |
| list_albumsA | All albums, including shared albums, with their folder and number of photos. |
| list_people_and_keywordsB | Names of people and keywords in the library with photo counts, most used first. |
| export_photosA | Copy photos to a folder, using the edited version where one exists. |
| osxphotos_helpA | Help for one osxphotos command, or the list of available commands if none is given. Pass a topic (one word, for example "location") to see only the options about it. |
| run_osxphotosA | Run an osxphotos command line command and return its output. |
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 7 tools
The native tools target distinct operations: facet listing, search, single-photo detail, album listing and export. The main overlap is `run_osxphotos`, a catch-all CLI escape hatch that duplicates search and export, but its description explicitly frames it as the fallback and even points to itself from `export_photos`, so an agent has clear guidance on which to pick.
Most tools follow a clean verb_noun snake_case pattern (list_albums, get_photo, search_photos, export_photos), with sensible singular/plural agreement. The two deviations — `osxphotos_help` (noun_help) and `run_osxphotos` (verb_server) — are minor but break the otherwise predictable scheme.
Seven tools is a well-scoped surface for a photo-library server: one for each core workflow (browse facets, browse albums, search, inspect, export) plus help and a CLI escape hatch. Nothing feels redundant or padded.
Read and export coverage is solid: discovery via albums/people/keywords, filtered search, full metadata retrieval and file export. Write-side operations (creating albums, editing keywords/people, deleting or importing photos) have no native tool and rely on `run_osxphotos` plus `osxphotos_help`, which is a workable but less discoverable gap.