Apple Photos MCP Server

A Model Context Protocol (MCP) server that enables AI assistants like Claude to query, search, export, and inspect the macOS Apple Photos library, backed by the osxphotos library.

Read-only against the Photos library. Exports write files to a directory you choose, but the library itself is never modified.

What is This?

This server acts as a bridge between AI assistants and Apple Photos. Once configured, you can ask Claude (or any MCP-compatible AI) to:

• "Find all my photos from our trip to Spain in 2023"

• "Show me my favorite sunset photos"

• "How many photos do I have? What are my top keywords?"

• "Find photos of Sarah from last summer and export them to ~/Desktop/sarah-summer"

• "List my albums"

• "Tell me everything about photo UUID ABC-123"

The AI assistant communicates with this server, which uses osxphotos to read the Photos library SQLite database directly. All data stays local on your machine.

Related MCP server: Google Photos MCP Server

Quick Start

Using Claude Code (Easiest)

If you're using Claude Code (in Terminal or VS Code), just ask Claude to install it:

Install the sweetrb/apple-photos-mcp MCP server so you can help me query my Apple Photos library

Claude will handle the installation and configuration automatically. The Python osxphotos dependency installs automatically on first use (a one-time, ~minute-long setup), so the only manual step is granting Full Disk Access — see Requirements below.

Using the Plugin Marketplace

Install as a Claude Code plugin for automatic configuration and enhanced AI behavior:

/plugin marketplace add sweetrb/apple-photos-mcp
/plugin install apple-photos

This method also installs a skill that teaches Claude when and how to use Apple Photos effectively.

Using the Codex Marketplace

The same plugin is available for Codex. Add the marketplace and install the plugin:

codex plugin marketplace add sweetrb/apple-photos-mcp
codex plugin add apple-photos@apple-photos-mcp

The Codex plugin runs the published apple-photos-mcp server through npx and ships the same Apple Photos skill, so behavior matches the Claude Code plugin. Because the server is a Python-sidecar (osxphotos) server, the first tool call after an npx launch auto-bootstraps a project-local Python venv with osxphotos (a one-time, ~minute-long setup), and the host process still needs Full Disk Access — see Requirements below.

Other Hosts (Hermes, Antigravity)

Configuration for two more hosts is included — each registers the same apple-photos MCP server (npx -y apple-photos-mcp). As a Python-sidecar (osxphotos) server it also needs Full Disk Access; see Requirements.

• Hermes Agent (NousResearch) — Hermes has no plugin/marketplace drop-in. Add the server with hermes mcp add apple-photos --command npx --args -y apple-photos-mcp, or merge .hermes-plugin/config.yaml into ~/.hermes/config.yaml. Details: .hermes-plugin/README.md.

• Antigravity (Google) — add the server entry from .antigravity-plugin/mcp_config.json to ~/.gemini/config/mcp_config.json (or via Antigravity's MCP settings).

Manual Installation

1. Install the server:

npm install -g github:sweetrb/apple-photos-mcp

2. Python deps install automatically. The first tool call auto-bootstraps a project-local Python venv with osxphotos (a one-time setup that can take ~a minute; progress is logged to stderr). You do not need to install anything by hand.

To skip the first-call delay, you can pre-warm the venv ahead of time:

pnpm run setup   # optional — pre-installs osxphotos so the first tool call is instant

Auto-setup needs Python 3, pip, and network access. If any are missing — or you disabled auto-setup via APPLE_PHOTOS_MCP_NO_AUTO_SETUP=1 — run pnpm run setup (or pip3 install osxphotos) yourself. See Configuration and Troubleshooting.

3. Add to Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "apple-photos": {
      "command": "npx",
      "args": ["apple-photos-mcp"]
    }
  }
}

4. Grant Full Disk Access to the app hosting the MCP server (Claude Desktop, Terminal, VS Code, etc.) — see Full Disk Access below.

5. Restart Claude Desktop and start using natural language:

"How many photos are in my library?"

Requirements

• macOS - The Photos library is macOS-only

• Node.js 20+ - Required for the MCP server

• Python 3.11+ - The server uses osxphotos under the hood and installs it automatically on first use into a project-local venv (one-time, ~a minute). You only need Python 3.11+, pip, and a network connection available. osxphotos requires Python ≥ 3.10 and the date filters need 3.11; macOS ships 3.9, so install a newer Python first (e.g. brew install python@3.12). Pre-warm it with pnpm run setup if you'd rather not wait on the first call.

• Apple Photos - Must have a Photos library (default location: ~/Pictures/Photos Library.photoslibrary)

• Full Disk Access - The Photos library lives in a protected directory. The host app needs Full Disk Access — see below and the Full Disk Access Setup Guide.

Features

Querying

Export

Diagnostics

Read tools also return structured JSON (structuredContent) alongside the human-readable text, so agents can consume results without parsing prose.

MCP resources & prompts

Resources expose read-only context the client can attach without a tool call: photos://library, photos://albums, photos://persons, photos://keywords, and the photos://photo/{uuid} template (full metadata for one photo). Prompts package common workflows: find-photos, export-photos, photo-summary.

Tool Reference

This section documents all available tools. AI agents should use these tool names and parameters exactly as specified.

Discovery

health-check

Verify osxphotos is installed and the Photos library can be opened.

Parameters: None

Returns: osxphotos version, library path, and total photo count — or an error if the library is inaccessible.

doctor

Run a full setup diagnostic: osxphotos installation, Photos library readability, and Full Disk Access — each reported as ok / warn / fail with an actionable message. This is the richer counterpart to health-check; reach for it first when a tool returns a permission or "unable to open" error.

Parameters: None

Returns: A per-check report. The structuredContent carries the raw { healthy, checks[] }, where each check has name, status (ok/warn/fail), and detail. The Full Disk Access check explicitly reports whether the host process can read the library — see Full Disk Access.

library-info

High-level stats about the Photos library.

Returns: Library path, Photos DB version, Photos.app version, counts of photos / movies / albums / folders / keywords / persons.

Query

query

Search the library with combinable filters. Returns photo summaries with UUIDs — use get-photo for full details on a specific match.

Example - Recent favorites of Sarah:

{
  "person": ["Sarah"],
  "favorite": true,
  "fromDate": "2025-06-01",
  "limit": 50
}

Example - Sunset keyword across two albums:

{
  "keyword": ["sunset"],
  "album": ["Vacation 2024", "Beach Trips"]
}

Returns: Photo summaries (UUID, filename, date, dimensions, favorite/hidden flags, albums, keywords, persons).

get-photo

Get full metadata for a single photo by UUID.

Example:

{
  "uuid": "33AC0410-D367-43AE-A839-12C7EF482020"
}

Returns: All metadata for the photo: dimensions, original dimensions, dates (taken/added/modified), title, description, location (lat/lon), place (name/country), albums, keywords, persons, labels, type flags (HDR / live / raw / edited / portrait / panorama / selfie / screenshot / slow-mo / time-lapse / burst), file paths (original, edited, raw, live-photo video), file size, UTI.

Browse

list-albums

List all albums in the library.

Returns: Each album's title, folder path, photo count, shared status, and UUID.

list-folders

List all folders in the library.

Returns: Each folder's title, parent folder, album count, and subfolder count.

list-keywords

List keywords sorted by usage count.

Returns: Keywords with their photo counts, sorted descending.

list-persons

List people detected by Photos face recognition, sorted by photo count.

Returns: Persons with their photo counts, sorted descending. Unidentified faces appear as _UNKNOWN_.

Export

export

Export one or more photos by UUID to a destination directory.

Example - Originals to a folder:

{
  "uuid": ["33AC0410-...", "EEFCEF1D-..."],
  "dest": "~/Desktop/exports"
}

Example - Edited versions plus raw and live-photo video:

{
  "uuid": ["33AC0410-..."],
  "dest": "~/Desktop/exports",
  "edited": true,
  "raw": true,
  "live": true,
  "overwrite": true
}

Returns: Destination path, count of files exported, count skipped, list of exported file paths, and any errors per UUID.

iCloud-only originals: If a photo's original isn't on disk (Photos is using "Optimize Mac Storage"), the export automatically falls back to Photos.app via AppleScript, which downloads the original on demand — same behavior as opening the photo in Photos. This is slower than a direct file copy; expect waits proportional to download size for large batches. Photos that genuinely can't be exported (e.g. edited=true requested but no edits exist) are still skipped with a per-UUID reason.

Usage Patterns

Basic Workflow

User: "How many photos do I have?"
AI: [calls library-info]
    "You have 30,968 items: 30,435 photos and 533 movies across 46 albums..."

User: "Find my favorite sunset photos"
AI: [calls query with keyword=["sunset"], favorite=true]
    "Found 12 favorite sunset photos. Here are the most recent..."

User: "Tell me about the first one"
AI: [calls get-photo with uuid="..."]
    "Taken on 2025-09-14 at 19:47, in Big Sur..."

Two-step: Query then Export

User: "Export all photos of Mollee from the beach to ~/Desktop/mollee-beach"
AI: [calls query with person=["Mollee"], keyword=["beach"]]
    "Found 109 photos."
AI: [calls export with the UUIDs and dest="~/Desktop/mollee-beach"]
    "Exported 109 files to ~/Desktop/mollee-beach."

Browsing Library Structure

User: "What are my top 10 keywords?"
AI: [calls list-keywords with limit=10]
    "Photo Stream (1561), Mollee (109), beach (109), 2015 Feb Keweenaw..."

User: "Who appears most in my photos?"
AI: [calls list-persons with limit=10]
    "Rita Sweet (29), Robert B Sweet (28), Jennifer Sweet (24)..."

Targeting a Different Library

By default, all operations use the system Photos library. To work with a different .photoslibrary:

User: "Show albums in my old archive at /Volumes/Archive/Photos.photoslibrary"
AI: [calls list-albums with library="/Volumes/Archive/Photos.photoslibrary"]
    "32 albums in the archive..."

Installation Options

npm (Recommended)

npm install -g github:sweetrb/apple-photos-mcp

osxphotos installs automatically on the first tool call — no separate pip3 install needed.

From Source (with Project-Local venv)

git clone https://github.com/sweetrb/apple-photos-mcp.git
cd apple-photos-mcp
pnpm install
pnpm run setup   # OPTIONAL — pre-builds ./venv with osxphotos; otherwise it's built on first use
pnpm run build

The pnpm run setup step is optional: if you skip it, the server auto-bootstraps the venv on the first tool call (one-time, ~a minute). Running it ahead of time just avoids that first-call delay.

If installed from source, use this configuration:

{
  "mcpServers": {
    "apple-photos": {
      "command": "node",
      "args": ["/path/to/apple-photos-mcp/build/index.js"]
    }
  }
}

The server prefers a project-local venv at ./venv/bin/python3 if present, and otherwise falls back to system python3. If neither has osxphotos, the server auto-builds the venv on first use (unless APPLE_PHOTOS_MCP_NO_AUTO_SETUP=1). The venv is also self-healing: it's picked up as soon as it exists — no server restart needed if you build or repair it while the server is running — and is rebuilt automatically if a package update changes its requirements.

Running from a clone in Claude Code (project-scope .mcp.json)

This repo ships a .mcp.json at its root so that, when you run claude from inside a clone, the server is registered automatically as a project-scope server — no manual config needed. Before launching, you must:

1. pnpm run build — compile the TypeScript to build/index.js.

2. pnpm run setup — optional; pre-builds the project-local venv at ./venv with osxphotos (the server prefers ./venv/bin/python3). Skip it and the server builds the venv on the first tool call.

3. Grant Full Disk Access to the app hosting Claude Code (Terminal, iTerm, VS Code, etc.) — the Photos library SQLite is in a protected directory and osxphotos reads it directly. See Full Disk Access.

Then launch Claude Code from the repo directory and approve the server when prompted.

The entrypoint is written as:

"args": ["${CLAUDE_PROJECT_DIR:-.}/build/index.js"]

CLAUDE_PROJECT_DIR is the variable Claude Code injects into a project/user-scoped server's environment, and it resolves to the repo root. You must launch claude from inside the repo for this to work — the bare . fallback is only a last resort and is not reliable, because it resolves against the launching process's working directory, not the repo.

Why not ${CLAUDE_PLUGIN_ROOT}? CLAUDE_PLUGIN_ROOT is set only for marketplace plugin installs, never for a project-scope clone, so it can't drive the clone workflow. Conversely, a plugin install can't use CLAUDE_PROJECT_DIR (in a plugin, that points at the user's project, not the plugin's own directory). Claude Code does not support nested defaults like ${CLAUDE_PLUGIN_ROOT:-${CLAUDE_PROJECT_DIR:-.}}, so a single entrypoint string cannot serve both contexts. The two distribution paths are therefore decoupled: the plugin carries its own MCP config in .claude-plugin/plugin.json (using ${CLAUDE_PLUGIN_ROOT}), while the root .mcp.json is dedicated to the clone workflow (using ${CLAUDE_PROJECT_DIR:-.}). Because plugin.json declares its own mcpServers, the plugin does not also auto-load the root .mcp.json, so there is no double-registration.

Heads-up on scope precedence: project-scope (.mcp.json) outranks user-scope. If you also have an apple-photos entry registered at user scope (e.g. an absolute path in ~/.claude.json), the project-scope entry wins and the user-scope one is ignored entirely. Pick one — for local development on this repo, the project-scope .mcp.json is the intended source. To pin a specific local build instead, register it at local scope (claude mcp add apple-photos -s local -- node /abs/path/build/index.js), which outranks project scope.

Full Disk Access

The Photos library SQLite database lives in a protected directory (~/Pictures/Photos Library.photoslibrary/database/). osxphotos reads this database directly — it does not go through Photos.app — so the host process needs Full Disk Access.

How to Grant Full Disk Access

1. Open System Settings (or System Preferences on older macOS)

2. Go to Privacy & Security > Full Disk Access

3. Click the + button

4. Add the application that hosts the MCP server:

   • Claude Desktop: Add /Applications/Claude.app

   • Terminal: Add /Applications/Utilities/Terminal.app

   • VS Code: Add /Applications/Visual Studio Code.app

   • iTerm: Add /Applications/iTerm.app

5. Restart the application after granting access

Verifying it worked

Run the doctor tool — it explicitly reports the Full Disk Access check (alongside osxphotos install and library readability) as ok / warn / fail, so it's the best way to confirm the grant took effect. health-check and library-info also work as a quick smoke test.

For the full why-and-how walkthrough, see the Full Disk Access Setup Guide.

Without Full Disk Access

The health-check tool will fail and report a permissions error, and doctor's Full Disk Access check will report fail. No tool will be able to open the library.

Configuration

All configuration is optional — the server works out of the box.

Environment variables

Configuration file (when the host strips env)

Some host apps (e.g. Claude Desktop) launch the MCP server with a scrubbed environment and ignore the env block in their server config, so there's no way to pass APPLE_PHOTOS_MCP_* settings through it. In that case, put them in a JSON file the host doesn't manage — APPLE_PHOTOS_MCP_CONFIG_FILE, or by default ~/Library/Application Support/apple-photos-mcp/config.json:

{
  "APPLE_PHOTOS_MCP_MAX_BUFFER": "209715200"
}

The server reads it at startup and merges values into the environment without overriding anything already set there (so an explicit env still wins). This is the recommended way to configure the server under Claude Desktop. Keep only non-secret config here.

Architecture

This package is a TypeScript MCP server with a Python sidecar:

• The MCP server (Node) speaks the Model Context Protocol over stdio.

• A bundled Python script (src/utils/photos_reader.py) uses osxphotos to read the Photos library and returns JSON.

• The TypeScript side spawns the Python script via child_process.execFileSync.

This is the same pattern used by apple-numbers-mcp for the numbers-parser Python library.

Security and Privacy

• Local only — All operations happen locally via osxphotos. No data is sent to external servers.

• Read-only against the Photos library — the library is never modified.

• Exports write to disk — export writes files to the destination directory you specify. Confirm destinations before running on shared machines.

• No credential storage — The server doesn't store any passwords or authentication tokens.

Known Limitations

For the full rundown — read-only scope, iCloud export caveats, face/album behavior, and library lag — see docs/LIMITATIONS.md. The summary below is the quick version.

Troubleshooting

The first tool call is slow / "setting up the Python venv" in the logs

• This is expected: it's the one-time automatic venv build (creating ./venv and installing osxphotos). It can take ~a minute and logs progress to stderr. Subsequent calls are fast. Pre-warm with pnpm run setup to avoid it.

• If the build keeps hitting a timeout on a slow network, raise APPLE_PHOTOS_MCP_SETUP_TIMEOUT (milliseconds; default 5 min).

"osxphotos not installed. Run: pnpm run setup"

• This only appears when automatic setup couldn't run — i.e. you set APPLE_PHOTOS_MCP_NO_AUTO_SETUP=1, or Python 3 / pip / network access is unavailable.

• Fix it by running pnpm run setup (project-local venv) or pip3 install osxphotos (global install) — or unset APPLE_PHOTOS_MCP_NO_AUTO_SETUP to re-enable auto-setup.

• If you used a virtualenv, make sure it's the one at ./venv/ in the project directory.

"Library not found" or permission errors

• Grant Full Disk Access to the host app — see Full Disk Access.

• Verify the library path: default is ~/Pictures/Photos Library.photoslibrary.

Photo not found / "Photo not found: "

• The UUID may be wrong — re-run query to get current UUIDs.

• The photo may have been deleted from the library.

Exports skip files with "missing"

• Since 0.1.3, the export auto-downloads iCloud-only originals via Photos.app, so this skip should be rare. If it still happens:

  • "original not downloaded from iCloud (download attempt returned no files)" — Photos.app couldn't fetch it. Check iCloud connectivity, that you're signed in, and that the photo isn't excluded by a Photos sync setting.

  • "no edited version exists" / "no raw sidecar exists" — edited=true or raw=true was requested but the photo doesn't have one. Retry without that flag.

Photos.app errors when running

• Closing Photos.app may resolve database-lock errors. osxphotos opens the library in read-only mode but still requires that no writer holds an exclusive lock.

apple-photos server fails to connect when run from a clone

• Launch claude from inside the repo directory so CLAUDE_PROJECT_DIR resolves to the repo root. The bare . fallback resolves against the launching process's working directory, not the repo, and is unreliable.

• Run pnpm run build first — the entrypoint ${CLAUDE_PROJECT_DIR:-.}/build/index.js won't exist until you compile.

• The ./venv with osxphotos builds automatically on the first tool call; run pnpm run setup only to pre-warm it, or if you've set APPLE_PHOTOS_MCP_NO_AUTO_SETUP=1.

• Grant Full Disk Access to the host app (Terminal, iTerm, VS Code, etc.) — see Full Disk Access.

• Run claude mcp list and check for conflicting scopes. Project-scope (.mcp.json) outranks user-scope; a stale user-scope apple-photos entry pointing at a bad path can mask the project-scope one. To pin a specific build, register it at local scope: claude mcp add apple-photos -s local -- node /abs/path/build/index.js.

• If the server shows as pending, approve the project-scope server when Claude Code prompts you.

Development

pnpm install            # Install dependencies
pnpm run setup          # Create ./venv with osxphotos
pnpm run build          # Compile TypeScript
pnpm test               # Run unit tests
pnpm run test:integration  # Run integration tests against the real Photos library
pnpm run test:all       # Unit + integration
pnpm run test:coverage  # Unit tests with coverage report
pnpm run typecheck      # Type-check without emitting
pnpm run lint           # Check code style
pnpm run format         # Format code

The Python sidecar is a thin CLI that the TypeScript layer shells out to:

./venv/bin/python3 src/utils/photos_reader.py library-info
./venv/bin/python3 src/utils/photos_reader.py query --keyword sunset --limit 5
./venv/bin/python3 src/utils/photos_reader.py export --uuid <uuid> --dest /tmp/out

Author

Rob Sweet - President, Superior Technologies Research

A software consulting, contracting, and development company.

• Email: rob@superiortech.io

• GitHub: @sweetrb

License

MIT License - see LICENSE for details. This project is not affiliated with Apple Inc. or the osxphotos project.

Contributing

Contributions are welcome! Please open an issue or PR at github.com/sweetrb/apple-photos-mcp.

Related Projects

Part of a family of macOS MCP servers:

• apple-mail-mcp — MCP server for Apple Mail (read, search, send, and organize email)

• apple-notes-mcp — MCP server for Apple Notes (create, search, update, and export notes)

• apple-numbers-mcp — MCP server for Apple Numbers (read and write .numbers spreadsheets)

• osxphotos — The Python library that powers this server

Recurring macOS permission prompts

If macOS keeps re-prompting for Full Disk Access or Automation for node (often after a brew upgrade), see docs/NODE-RUNTIME-AND-TCC-PERMISSIONS.md — the fix is to run this server under the official, Developer-ID-signed Node so the grant survives Node updates.