Skip to main content
Glama
README.md
<p align="center">
  <img src="assets/banner.svg" alt="osxphotos-mcp: your Apple Photos library, for AI assistants" width="760">
</p>

<p align="center">
  <a href="https://github.com/rscholz98/osxphotos-mcp/actions/workflows/ci.yml"><img src="https://github.com/rscholz98/osxphotos-mcp/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license"></a>
  <img src="https://img.shields.io/badge/python-3.11+-blue" alt="Python 3.11+">
  <img src="https://img.shields.io/badge/platform-macOS-lightgrey" alt="macOS">
  <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-server-8a2be2" alt="MCP server"></a>
  <a href="https://github.com/RhetTbull/osxphotos"><img src="https://img.shields.io/badge/built%20on-osxphotos-f97316" alt="Built on osxphotos"></a>
</p>

A slim [MCP](https://modelcontextprotocol.io) 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](https://github.com/RhetTbull/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

```mermaid
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")]
```

## Install

You need macOS and [uv](https://docs.astral.sh/uv/).

**Claude Code**

```sh
claude mcp add photos -- uvx --from git+https://github.com/rscholz98/osxphotos-mcp osxphotos-mcp
```

**Claude Desktop and other MCP clients**

```json
{
  "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

```sh
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:

```sh
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.

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.