Skip to main content
Glama

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-mcp

Claude 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

search_photos

Find photos by text, date range, album, person, keyword, place, favorite or media type, with paging

get_photo

Full details of one photo: metadata, albums, labels, camera, location, file paths

list_albums

Albums, including shared ones, with folder and photo count

list_people_and_keywords

People and keywords with photo counts

export_photos

Copy photos to a folder (edited version if there is one, never overwrites)

osxphotos_help

Look up any osxphotos command and its options

run_osxphotos

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

--library PATH

Use this Photos library instead of the system library

--allow-write

Enable commands that change your library (add-locations, batch-edit, import, push-exif, sync, timewarp) and options that overwrite or delete files or change an export database (--overwrite, --report, --save-config, --cleanup, exportdb --sql and similar)

--include-hidden

Include photos you have hidden in Photos. Also needed for commands that cannot filter them, such as timewarp

--preload

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 --update does 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 commands batch-edit, import and timewarp.

  • Options that run code (--post-command, --post-function, --query-eval and similar) are always refused, as are the interactive commands.

  • export writes 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 pytest

Most 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.photoslibrary

License

MIT. osxphotos is also MIT licensed, © Rhet Turnbull.

Available Tools

7 tools
export_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_photoB
Read-only

Full details of one photo: metadata, albums, labels, camera, location and file paths.

Inputs: uuid (required). Returns: object

list_albumsA
Read-only

All albums, including shared albums, with their folder and number of photos.

Inputs: no named parameters. Returns: object

list_people_and_keywordsB
Read-only

Names of people and keywords in the library with photo counts, most used first.

Inputs: no named parameters. Returns: object

osxphotos_helpA
Read-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_photosA
Read-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

    A3.7/5.0

    Scored across 7 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    Related MCP Servers

    • A
      license
      A
      quality
      A
      maintenance
      Enables AI assistants to query and export from the macOS Apple Photos library using natural language, backed by osxphotos.
      21
      811 npm
      51
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      This MCP server enables AI tools to interact with your Apple Photos library via the osxphotos CLI, providing tools for querying and managing photos.
      2
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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 npm
      MIT