osxphotos-mcp
osxphotos-mcp lets an AI assistant search, inspect, and export an Apple Photos library over MCP, read-only by default, with on-demand access to osxphotos CLI help and commands.
Search photos and videos by text, date range, album, person, keyword, place, favorite, and media type, with paging and total match counts.
Get full details for a photo by UUID, including metadata, albums, labels, camera, location, and file paths.
List all albums, including shared albums, with folders and photo counts.
List people and keywords with photo counts, most used first.
Export selected photos to a folder, preferring edited versions, without overwriting existing files; non-downloaded iCloud photos are reported as skipped.
Look up osxphotos commands and options with
osxphotos_help.Run arbitrary osxphotos CLI commands with
run_osxphotos, subject to safety restrictions.Operate read-only by default; optionally enable library-changing/write operations with
--allow-write.Exclude hidden photos by default; optionally include them with
--include-hidden.Use a custom Photos library path and optionally preload the library at startup.
Provides tools for searching, inspecting, and exporting an Apple Photos library, including finding photos by text, date, album, person, keyword, place, favorite or media type, retrieving full photo metadata, listing albums and people, and copying photos to a folder.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@osxphotos-mcp find photos from my Yosemite trip last summer"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A slim MCP server that lets an AI assistant search, inspect and export your Apple Photos library. Seven tools, read-only by default.
It is a thin layer over osxphotos by Rhet Turnbull, which does all the real work of reading the Photos library. If this is useful to you, the credit belongs there.
How it works
flowchart LR
A["AI assistant<br/>Claude, Zed, ..."] -- "MCP over stdio" --> S["osxphotos-mcp"]
S --> T["5 typed tools<br/>search, details, albums,<br/>people, export"]
S --> P["2 passthrough tools<br/>osxphotos_help, run_osxphotos"]
T -- "Python API" --> O["osxphotos"]
P -- "command line,<br/>unsafe options refused" --> O
O -- "reads" --> L[("Photos library")]Related MCP server: mcp-osxphotos
Install
You need macOS and uv.
Claude Code
claude mcp add photos -- uvx --from git+https://github.com/rscholz98/osxphotos-mcp osxphotos-mcpClaude Desktop and other MCP clients
{
"mcpServers": {
"photos": {
"command": "uvx",
"args": ["--from", "git+https://github.com/rscholz98/osxphotos-mcp", "osxphotos-mcp"]
}
}
}Then give the app that runs the server (Claude, your terminal, ...) Full Disk Access under System Settings > Privacy & Security. Without it, macOS blocks access to the library.
If the client cannot find uvx, use its full path (which uvx).
Each start of the server uses the latest version from this repository, so restarting the client updates it. To stay on one version, add its tag to the URL: git+https://github.com/rscholz98/osxphotos-mcp@v0.3.0.
Tools
Tool | What it does |
| Find photos by text, date range, album, person, keyword, place, favorite or media type, with paging |
| Full details of one photo: metadata, albums, labels, camera, location, file paths |
| Albums, including shared ones, with folder and photo count |
| People and keywords with photo counts |
| Copy photos to a folder (edited version if there is one, never overwrites) |
| Look up any osxphotos command and its options |
| Run any osxphotos command, for everything the tools above don't cover |
The first five are small and typed, so a model gets them right on the first try. The last two reach the rest of osxphotos on demand, without loading hundreds of options into every conversation.
The server keeps the library in memory and reloads it in the background when it changes, so new or edited photos can take about five minutes to show up.
Options
Add these after osxphotos-mcp in the command or args:
Option | Effect |
| Use this Photos library instead of the system library |
| Enable commands that change your library ( |
| Include photos you have hidden in Photos. Also needed for commands that cannot filter them, such as |
| Load the library when the server starts, so the first request need not wait for it. Loading 65,000 photos takes about 7 seconds, and the loaded library holds about 2 GB of memory, which is why this is off by default |
Safety
Nothing changes your Photos library or an export database, and no existing file is overwritten or deleted, unless you start the server with
--allow-write. Exporting into a folder again with--updatedoes replace files that an earlier export put there.Photos you have hidden in Photos stay out of every tool's results and counts unless you start the server with
--include-hidden. Commands that cannot filter them are refused without it:albums,persons,keywords,labels,places,info,dump,compare,exportdb,exiftool, and the write commandsbatch-edit,importandtimewarp.Options that run code (
--post-command,--post-function,--query-evaland similar) are always refused, as are the interactive commands.exportwrites new files wherever the model points it, and the option filter is a best effort, not a sandbox. Give this server to assistants you would trust with the osxphotos command line.
Development
git clone https://github.com/rscholz98/osxphotos-mcp && cd osxphotos-mcp
uv sync
uv run pytestMost tests read two of osxphotos' own test libraries and are skipped without them:
git clone --depth 1 --branch v0.78.1 --filter=blob:none --sparse https://github.com/RhetTbull/osxphotos.git /tmp/osxphotos
git -C /tmp/osxphotos sparse-checkout set tests/Test-13.0.0.photoslibrary tests/Test-Shared-10.15.1.photoslibrary
export OSXPHOTOS_MCP_TEST_LIBRARY=/tmp/osxphotos/tests/Test-13.0.0.photoslibraryLicense
MIT. osxphotos is also MIT licensed, © Rhet Turnbull.
Available Tools
7 toolsexport_photosA
Copy photos to a folder, using the edited version where one exists.
Never overwrites existing files. Photos that are not downloaded from iCloud are
reported as skipped. For more control, use run_osxphotos with the export command.
Inputs: uuids (required), destination (required). Returns: object
get_photoBRead-only
Full details of one photo: metadata, albums, labels, camera, location and file paths.
Inputs: uuid (required). Returns: object
list_albumsARead-only
All albums, including shared albums, with their folder and number of photos.
Inputs: no named parameters. Returns: object
list_people_and_keywordsBRead-only
Names of people and keywords in the library with photo counts, most used first.
Inputs: no named parameters. Returns: object
osxphotos_helpARead-only
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.
Inputs: topic, command. Returns: result
run_osxphotosA
Run an osxphotos command line command and return its output.
Pass options as separate items, for example command "query" with args
["--no-location", "--json"]. Call osxphotos_help first to see a command's options.
Inputs: command (required), args. Returns: result
search_photosARead-only
Find photos and videos, newest first. All filters are optional and combine with AND.
text matches title, description, filename, people, keywords, albums, labels and place.
Dates are ISO (YYYY-MM-DD, optionally with a time) in the photo's local time; to_date
includes that whole day. album, person and keyword are exact names, ignoring case.
Returns the total number of matches and up to `limit` (max 100) of them.
Inputs: text, album, limit, place, +6 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
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.
Related MCP Connectors
Search photos and video moments by visual meaning, people, dates, and folders across local libraries, Apple Photos, and OneDrive. Manage collections, groups, favorites, people, and duplicate review. Synced metadata remains searchable while the desktop is offline; local and Apple Photos media access needs the owning device online with remote access enabled. OneDrive media can be accessed directly from the cloud. OAuth or Bearer API keys. Paid Cloud Access required; hosted visual search uses prepaid credits. Text-in-image search is semantic matching, not guaranteed exact OCR. Setup: https://organizewith.ai/en/guides/connect-ai-assistants
MCP connector that lets ChatGPT list, search, and run your Apple Shortcuts via a local Mac agent
Search, read, and write your Apple Notes from ChatGPT/Claude via a local Mac agent + MCP relay.
Official MCP bridge to Exogram—the Personal AI Agent for your work, people, and life.
Related MCP Servers
- AlicenseAqualityAmaintenanceEnables AI assistants to query and export from the macOS Apple Photos library using natural language, backed by osxphotos.21811 npm51MIT
- AlicenseNot gradedqualityDmaintenanceThis MCP server enables AI tools to interact with your Apple Photos library via the osxphotos CLI, providing tools for querying and managing photos.2MIT
- AlicenseAqualityBmaintenanceEnables AI agents to search, inspect, organize, and export photos from a local Apple Photos library using natural language, including scene labels, text, faces, places, and albums.131MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to search, list, preview, and export photos from Apple Photos, Google Photos Picker sessions, and local Google Takeout archives using native search and metadata inspection.6 npmMIT